@katerynakhar/i18n-keeper 0.16.0

package/src/formats/json-write.ts

@@ -0,0 +1,66 @@
+import { FormatError } from './error.js';
+import type { Edit, WriteOutcome } from './write.js';
+
+/**
+ * JSON is the one format that can be re-serialised without losing anything —
+ * it has no comments, no anchors and no styles to preserve. Key order is kept
+ * because setting an existing key leaves it where it is, and new keys append.
+ */
+export function writeJsonLocale(
+  content: string,
+  file: string,
+  _locale: string,
+  edits: Edit[],
+): WriteOutcome {
+  let root: Record<string, unknown> = {};
+
+  if (content.trim() !== '') {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(content);
+    } catch (err) {
+      throw new FormatError(file, err instanceof Error ? err.message : String(err));
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      throw new FormatError(file, 'expected an object at the top level');
+    }
+    root = parsed as Record<string, unknown>;
+  }
+
+  const skipped: Array<{ key: string; reason: string }> = [];
+
+  for (const edit of edits) {
+    const path = edit.key.split('.');
+    let node = root;
+    let blocked: string | null = null;
+
+    for (const [index, segment] of path.entries()) {
+      if (index === path.length - 1) {
+        const existing = node[segment];
+        if (existing !== undefined && typeof existing === 'object' && existing !== null) {
+          blocked = `${segment} holds a collection, not a string`;
+          break;
+        }
+        node[segment] = edit.value;
+        break;
+      }
+
+      const next = node[segment];
+      if (next === undefined) {
+        const created: Record<string, unknown> = {};
+        node[segment] = created;
+        node = created;
+        continue;
+      }
+      if (typeof next !== 'object' || next === null || Array.isArray(next)) {
+        blocked = `${segment} already holds a value`;
+        break;
+      }
+      node = next as Record<string, unknown>;
+    }
+
+    if (blocked) skipped.push({ key: edit.key, reason: blocked });
+  }
+
+  return { content: `${JSON.stringify(root, null, 2)}\n`, skipped };
+}

package/src/formats/json.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import type { ReadTarget } from '../types.js';
+import { FormatError } from './error.js';
+import { flattenValue } from './flatten.js';
+
+export class ParseError extends FormatError {}
+
+/** Flattens one JSON locale file into dot-notation keys under an optional namespace. */
+export function readJsonLocale(
+  file: string,
+  namespace: string,
+  _locale: string,
+  _isSource: boolean,
+  target: ReadTarget,
+): void {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new ParseError(file, err instanceof Error ? err.message : String(err));
+  }
+  if (Array.isArray(parsed)) {
+    target.skipped.push({ file, reason: 'the file holds a list, not keyed translations' });
+    return;
+  }
+  flattenValue(parsed, namespace, file, target.leaves, target.containers);
+}

package/src/formats/php-write.ts

@@ -0,0 +1,146 @@
+import { parsePhpLayout, type ArraySlot, type ArrayStyle } from './php.js';
+import { spliceAll, type Edit, type WriteOutcome } from './write.js';
+
+/** Nested levels that have to be created get this much extra indentation. */
+const INDENT_STEP = '    ';
+
+const SHORT_ESCAPES = new Map<number, string>([
+  [0x0a, '\\n'],
+  [0x0d, '\\r'],
+  [0x09, '\\t'],
+  [0x0b, '\\v'],
+  [0x0c, '\\f'],
+  [0x1b, '\\e'],
+]);
+
+function hasControlCharacter(value: string): boolean {
+  for (const ch of value) {
+    if (ch.codePointAt(0)! < 0x20) return true;
+  }
+  return false;
+}
+
+/**
+ * A PHP string literal for an arbitrary value.
+ *
+ * Single quotes are preferred because nothing interpolates inside them: `$` and
+ * Laravel's `:name` stay literal, which is exactly what a language file wants.
+ * Control characters have no single-quoted spelling, so those fall back to
+ * double quotes with escapes.
+ */
+export function phpLiteral(value: string): string {
+  if (!hasControlCharacter(value)) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  }
+
+  let out = '';
+  for (const ch of value) {
+    const cp = ch.codePointAt(0)!;
+    if (cp >= 0x20) {
+      if (ch === '\\' || ch === '"' || ch === '$') out += `\\${ch}`;
+      else out += ch;
+      continue;
+    }
+    out += SHORT_ESCAPES.get(cp) ?? `\\x${cp.toString(16).padStart(2, '0')}`;
+  }
+  return `"${out}"`;
+}
+
+const OPEN: Record<ArrayStyle, string> = { bracket: '[', array: 'array(' };
+const CLOSE: Record<ArrayStyle, string> = { bracket: ']', array: ')' };
+
+/** `'a' => ['b' => 'value'],` for however many levels are missing. */
+function nestedEntry(keys: string[], value: string, indent: string, style: ArrayStyle): string {
+  const [head, ...rest] = keys;
+  if (rest.length === 0) return `${indent}${phpLiteral(head!)} => ${phpLiteral(value)},`;
+  return [
+    `${indent}${phpLiteral(head!)} => ${OPEN[style]}`,
+    nestedEntry(rest, value, indent + INDENT_STEP, style),
+    `${indent}${CLOSE[style]},`,
+  ].join('\n');
+}
+
+/**
+ * An empty language file shaped like the one it is being translated from, so a
+ * project written with `array()` does not suddenly gain a file that is not.
+ */
+export function blankPhpFile(sourceContent: string | null): string {
+  let style: ArrayStyle = 'bracket';
+  if (sourceContent !== null) {
+    try {
+      style = parsePhpLayout(sourceContent, '<source>').layout.arrays.get('')?.style ?? 'bracket';
+    } catch {
+      // An unreadable source is no reason to refuse to create the target.
+    }
+  }
+  return `<?php\n\nreturn ${OPEN[style]}\n${CLOSE[style]};\n`;
+}
+
+/** The deepest array that already exists on the way to `key`. */
+function parentFor(
+  arrays: Map<string, ArraySlot>,
+  key: string,
+): { slot: ArraySlot; remaining: string[] } | null {
+  const parts = key.split('.');
+  for (let depth = parts.length - 1; depth >= 0; depth--) {
+    const slot = arrays.get(parts.slice(0, depth).join('.'));
+    if (slot) return { slot, remaining: parts.slice(depth) };
+  }
+  return null;
+}
+
+export function writePhpLocale(
+  content: string,
+  file: string,
+  _locale: string,
+  edits: Edit[],
+): WriteOutcome {
+  const { layout } = parsePhpLayout(content, file);
+  const skipped: Array<{ key: string; reason: string }> = [];
+  const splices: Array<{ start: number; end: number; text: string }> = [];
+
+  // Several new keys can belong in the same array and share one insertion
+  // point, so they are collected and emitted together, in order.
+  const insertions = new Map<number, { slot: ArraySlot; lines: string[] }>();
+
+  for (const edit of edits) {
+    const span = layout.values.get(edit.key);
+    if (span) {
+      splices.push({ start: span.start, end: span.end, text: phpLiteral(edit.value) });
+      continue;
+    }
+
+    if (layout.arrays.has(edit.key)) {
+      skipped.push({ key: edit.key, reason: 'the key holds an array, not a string' });
+      continue;
+    }
+
+    const parent = parentFor(layout.arrays, edit.key);
+    if (!parent) {
+      skipped.push({ key: edit.key, reason: 'no array to insert into' });
+      continue;
+    }
+
+    const entry = nestedEntry(parent.remaining, edit.value, parent.slot.indent, parent.slot.style);
+    const bucket = insertions.get(parent.slot.insertAt);
+    if (bucket) bucket.lines.push(entry);
+    else insertions.set(parent.slot.insertAt, { slot: parent.slot, lines: [entry] });
+  }
+
+  for (const [at, { slot, lines }] of insertions) {
+    const body = lines.join('\n');
+    // An empty array usually already has a newline before its closing bracket;
+    // adding a second one would leave a blank line in the file.
+    const closingOnNextLine = content.slice(at).startsWith('\n');
+    const text = slot.empty
+      ? closingOnNextLine
+        ? `\n${body}`
+        : `\n${body}\n`
+      : slot.hasTrailingComma
+        ? `\n${body}`
+        : `,\n${body}`;
+    splices.push({ start: at, end: at, text });
+  }
+
+  return { content: spliceAll(content, splices), skipped };
+}

package/src/formats/php.ts

@@ -0,0 +1,414 @@
+import { readFileSync } from 'node:fs';
+import type { ReadTarget } from '../types.js';
+import { FormatError } from './error.js';
+import { flattenValue, type PlainValue } from './flatten.js';
+
+/**
+ * Parses the `<?php return [...];` subset that Laravel language files use.
+ *
+ * Deliberately a parser and not an evaluator: locale files come from the
+ * repository being linted, so running them would mean executing untrusted code,
+ * and it would force PHP onto every machine running the linter. Anything
+ * outside the literal subset is a clear error rather than a guess.
+ */
+
+export class PhpParseError extends FormatError {
+  constructor(file: string, line: number, message: string) {
+    super(file, message, line);
+  }
+}
+
+const IDENT_START = /[A-Za-z_\x80-￿]/;
+
+/** Where a value sits in the source text, so it can be replaced in place. */
+export interface ValueSpan {
+  start: number;
+  end: number;
+}
+
+/** `array(...)` still turns up in older projects; new entries should match. */
+export type ArrayStyle = 'bracket' | 'array';
+
+/** Where a new entry can be inserted into an existing array. */
+export interface ArraySlot {
+  style: ArrayStyle;
+  /** Just past the last entry's value, or just past the opening bracket. */
+  insertAt: number;
+  /** Indentation the entries use, so an inserted one lines up. */
+  indent: string;
+  hasTrailingComma: boolean;
+  empty: boolean;
+}
+
+export interface PhpLayout {
+  /** Dot path -> the span of its value expression. */
+  values: Map<string, ValueSpan>;
+  /** Dot path of every array ('' for the returned one) -> where to insert. */
+  arrays: Map<string, ArraySlot>;
+}
+
+class Parser {
+  private pos = 0;
+  readonly layout: PhpLayout = { values: new Map(), arrays: new Map() };
+
+  constructor(
+    private readonly text: string,
+    private readonly file: string,
+  ) {}
+
+  /** The indentation of the line `at` sits on. */
+  private indentAt(at: number): string {
+    const lineStart = this.text.lastIndexOf('\n', at - 1) + 1;
+    const match = /^[ \t]*/.exec(this.text.slice(lineStart, at));
+    return match ? match[0] : '';
+  }
+
+  private lineAt(pos: number): number {
+    let line = 1;
+    for (let i = 0; i < pos && i < this.text.length; i++) {
+      if (this.text[i] === '\n') line++;
+    }
+    return line;
+  }
+
+  private error(message: string, pos = this.pos): never {
+    throw new PhpParseError(this.file, this.lineAt(pos), message);
+  }
+
+  private atEnd(): boolean {
+    return this.pos >= this.text.length;
+  }
+
+  /** Whitespace and all three PHP comment styles. */
+  private skipTrivia(): void {
+    for (;;) {
+      while (!this.atEnd() && /\s/.test(this.text[this.pos]!)) this.pos++;
+
+      if (this.text.startsWith('//', this.pos) || this.text.startsWith('#', this.pos)) {
+        const nl = this.text.indexOf('\n', this.pos);
+        this.pos = nl === -1 ? this.text.length : nl + 1;
+        continue;
+      }
+      if (this.text.startsWith('/*', this.pos)) {
+        const end = this.text.indexOf('*/', this.pos + 2);
+        if (end === -1) this.error('Unterminated block comment');
+        this.pos = end + 2;
+        continue;
+      }
+      return;
+    }
+  }
+
+  private eat(token: string): boolean {
+    this.skipTrivia();
+    if (this.text.startsWith(token, this.pos)) {
+      this.pos += token.length;
+      return true;
+    }
+    return false;
+  }
+
+  private eatKeyword(word: string): boolean {
+    this.skipTrivia();
+    const slice = this.text.slice(this.pos, this.pos + word.length);
+    if (slice.toLowerCase() !== word) return false;
+    const next = this.text[this.pos + word.length];
+    if (next !== undefined && /[\w]/.test(next)) return false;
+    this.pos += word.length;
+    return true;
+  }
+
+  private expect(token: string, what = token): void {
+    if (!this.eat(token)) this.error(`Expected ${what}`);
+  }
+
+  parseFile(): PlainValue {
+    const open = this.text.indexOf('<?php');
+    if (open === -1) this.error('Missing <?php opening tag', 0);
+    this.pos = open + '<?php'.length;
+
+    // `declare(strict_types=1);` and similar preamble statements.
+    while (this.eatKeyword('declare')) {
+      const close = this.text.indexOf(')', this.pos);
+      if (close === -1) this.error('Unterminated declare()');
+      this.pos = close + 1;
+      this.eat(';');
+    }
+
+    if (!this.eatKeyword('return')) {
+      this.error('Expected `return` — a language file must return an array');
+    }
+
+    const value = this.parseValue('');
+    this.expect(';');
+
+    this.skipTrivia();
+    if (this.eat('?>')) this.skipTrivia();
+    if (!this.atEnd()) this.error('Unexpected content after the returned array');
+
+    return value;
+  }
+
+  private parseValue(path: string): PlainValue {
+    this.skipTrivia();
+    if (this.atEnd()) this.error('Unexpected end of file');
+
+    const ch = this.text[this.pos]!;
+
+    if (ch === '[') {
+      this.pos++;
+      return this.parseArrayBody(']', path);
+    }
+    if (this.eatKeyword('array')) {
+      this.expect('(', '( after array');
+      return this.parseArrayBody(')', path);
+    }
+    if (ch === "'") return this.parseSingleQuoted();
+    if (ch === '"') return this.parseDoubleQuoted();
+    if (this.eatKeyword('true')) return true;
+    if (this.eatKeyword('false')) return false;
+    if (this.eatKeyword('null')) return null;
+    if (/[-+\d.]/.test(ch)) return this.parseNumber();
+
+    if (ch === '$') this.error('Variables are not supported in language files');
+    if (this.text.startsWith('<<<', this.pos)) {
+      this.error('Heredoc/nowdoc strings are not supported');
+    }
+    if (IDENT_START.test(ch)) this.error('Constants and function calls are not supported');
+
+    this.error(`Unexpected character ${JSON.stringify(ch)}`);
+  }
+
+  private parseArrayBody(closing: string, path: string): PlainValue {
+    const entries: Array<[string | number, PlainValue]> = [];
+    let nextIndex = 0;
+    let sawStringKey = false;
+
+    const afterOpen = this.pos;
+    let indent = '';
+    let lastValueEnd = afterOpen;
+    let hasTrailingComma = false;
+
+    for (;;) {
+      this.skipTrivia();
+      if (this.eat(closing)) break;
+      if (this.atEnd()) this.error(`Unterminated array, expected ${closing}`);
+
+      const start = this.pos;
+      if (indent === '') indent = this.indentAt(start);
+      const first = this.parseValue(path);
+
+      if (this.eat('=>')) {
+        let key: string | number;
+        if (typeof first === 'string') {
+          sawStringKey = true;
+          key = first;
+        } else if (typeof first === 'number' && Number.isInteger(first)) {
+          nextIndex = Math.max(nextIndex, first + 1);
+          key = first;
+        } else {
+          this.error('Array keys must be strings or integers', start);
+        }
+        entries.push([key, this.recordValue(path, String(key))]);
+      } else {
+        const key = nextIndex++;
+        // A list entry's value was already consumed as `first`; its span runs
+        // from where the entry started to where parsing left off.
+        this.layout.values.set(join(path, String(key)), { start, end: this.pos });
+        entries.push([key, first]);
+      }
+
+      lastValueEnd = this.pos;
+      this.skipTrivia();
+      if (this.eat(',')) {
+        hasTrailingComma = true;
+        // Past the comma, so an inserted entry lands after it rather than
+        // between the value and its separator.
+        lastValueEnd = this.pos;
+        continue;
+      }
+      hasTrailingComma = false;
+      this.expect(closing, `, or ${closing}`);
+      break;
+    }
+
+    this.layout.arrays.set(path, {
+      style: closing === ')' ? 'array' : 'bracket',
+      insertAt: entries.length === 0 ? afterOpen : lastValueEnd,
+      indent: indent || '    ',
+      hasTrailingComma,
+      empty: entries.length === 0,
+    });
+
+    // PHP arrays are ordered maps; a purely sequential one is a JS array.
+    const sequential =
+      !sawStringKey && entries.every(([key], i) => typeof key === 'number' && key === i);
+    if (sequential) return entries.map(([, value]) => value);
+
+    const object: Record<string, PlainValue> = {};
+    for (const [key, value] of entries) object[String(key)] = value;
+    return object;
+  }
+
+  private recordValue(path: string, key: string): PlainValue {
+    this.skipTrivia();
+    const start = this.pos;
+    const value = this.parseValue(join(path, key));
+    this.layout.values.set(join(path, key), { start, end: this.pos });
+    return value;
+  }
+
+  private parseNumber(): number {
+    this.skipTrivia();
+    const match = /^[-+]?(?:\d[\d_]*\.?[\d_]*|\.\d[\d_]*)(?:[eE][-+]?\d+)?/.exec(
+      this.text.slice(this.pos),
+    );
+    if (!match || match[0] === '') this.error('Malformed number');
+    this.pos += match[0].length;
+    return Number(match[0].replace(/_/g, ''));
+  }
+
+  /** Single quotes escape only \' and \\; everything else is literal. */
+  private parseSingleQuoted(): string {
+    const start = this.pos;
+    this.pos++;
+    let out = '';
+    while (!this.atEnd()) {
+      const ch = this.text[this.pos]!;
+      if (ch === '\\') {
+        const next = this.text[this.pos + 1];
+        if (next === "'" || next === '\\') {
+          out += next;
+          this.pos += 2;
+          continue;
+        }
+        out += ch;
+        this.pos++;
+        continue;
+      }
+      if (ch === "'") {
+        this.pos++;
+        return out;
+      }
+      out += ch;
+      this.pos++;
+    }
+    this.error('Unterminated string', start);
+  }
+
+  private parseDoubleQuoted(): string {
+    const start = this.pos;
+    this.pos++;
+    let out = '';
+    while (!this.atEnd()) {
+      const ch = this.text[this.pos]!;
+
+      if (ch === '"') {
+        this.pos++;
+        return out;
+      }
+
+      if (ch === '$') {
+        const next = this.text[this.pos + 1];
+        if (next !== undefined && (IDENT_START.test(next) || next === '{')) {
+          this.error('Variable interpolation is not supported in language files');
+        }
+        out += ch;
+        this.pos++;
+        continue;
+      }
+
+      if (ch === '{' && this.text[this.pos + 1] === '$') {
+        this.error('Variable interpolation is not supported in language files');
+      }
+
+      if (ch === '\\') {
+        out += this.readEscape();
+        continue;
+      }
+
+      out += ch;
+      this.pos++;
+    }
+    this.error('Unterminated string', start);
+  }
+
+  private readEscape(): string {
+    const next = this.text[this.pos + 1];
+    if (next === undefined) this.error('Unterminated escape sequence');
+
+    const simple: Record<string, string> = {
+      n: '\n',
+      r: '\r',
+      t: '\t',
+      v: '\v',
+      f: '\f',
+      e: '\x1b',
+      '\\': '\\',
+      $: '$',
+      '"': '"',
+    };
+    if (next in simple) {
+      this.pos += 2;
+      return simple[next]!;
+    }
+
+    if (next === 'x') {
+      const match = /^[0-9A-Fa-f]{1,2}/.exec(this.text.slice(this.pos + 2));
+      if (match) {
+        this.pos += 2 + match[0].length;
+        return String.fromCharCode(Number.parseInt(match[0], 16));
+      }
+    }
+
+    if (next === 'u' && this.text[this.pos + 2] === '{') {
+      const close = this.text.indexOf('}', this.pos + 3);
+      const hex = close === -1 ? '' : this.text.slice(this.pos + 3, close);
+      if (close !== -1 && /^[0-9A-Fa-f]+$/.test(hex)) {
+        this.pos = close + 1;
+        return String.fromCodePoint(Number.parseInt(hex, 16));
+      }
+      this.error('Malformed \\u{...} escape');
+    }
+
+    const octal = /^[0-7]{1,3}/.exec(this.text.slice(this.pos + 1));
+    if (octal) {
+      this.pos += 1 + octal[0].length;
+      return String.fromCharCode(Number.parseInt(octal[0], 8) & 0xff);
+    }
+
+    // PHP keeps an unrecognised escape as a literal backslash plus the character.
+    this.pos += 1;
+    return '\\';
+  }
+}
+
+function join(path: string, key: string): string {
+  return path ? `${path}.${key}` : key;
+}
+
+export function parsePhp(text: string, file: string): PlainValue {
+  return new Parser(text, file).parseFile();
+}
+
+/** Parses and also reports where every value and array sits in the text. */
+export function parsePhpLayout(text: string, file: string): { value: PlainValue; layout: PhpLayout } {
+  const parser = new Parser(text, file);
+  const value = parser.parseFile();
+  return { value, layout: parser.layout };
+}
+
+export function readPhpLocale(
+  file: string,
+  namespace: string,
+  _locale: string,
+  _isSource: boolean,
+  target: ReadTarget,
+): void {
+  const parsed = parsePhp(readFileSync(file, 'utf8'), file);
+  if (Array.isArray(parsed)) {
+    target.skipped.push({ file, reason: 'the file holds a list, not keyed translations' });
+    return;
+  }
+  flattenValue(parsed, namespace, file, target.leaves, target.containers);
+}