champollion 0.3.3 → 0.4.0

package/lib/file-scope.js

@@ -0,0 +1,106 @@
+/**
+ * file-scope.js — `sync --files <glob>` and `sync --retranslate <glob>`.
+ *
+ * Dogfood 2026-08-28, finding 3: the only way to translate a subset of
+ * files was hand-editing .champollion-content.lock — and deleting a lock
+ * entry did not even work, because the sync then ADOPTED the existing
+ * target as hand-translated instead of re-translating it.
+ *
+ *   --files <glob>        Only these content files are considered this run
+ *                         (the rest are untouched, not even scanned).
+ *   --retranslate <glob>  These content files are translated FRESH: the
+ *                         lock, the adoption rule and the Translation
+ *                         Memory are all bypassed for them. You named the
+ *                         file, so this is the one place a run overwrites a
+ *                         target it would otherwise keep — and pays for it.
+ *
+ * Patterns match the path the sync prints for a file: relative to the
+ * content directory for Hugo ("posts/hello.md"), and prefixed with the
+ * content folder for Docusaurus ("docs/intro.md", "blog/launch.md").
+ * A contentDir project ALSO matches the path from the project root
+ * ("newsletter/2026-10.md" for newsletter/2026-10.md): the repair hint a
+ * sync printed (`--redo files:2026-10.md --fresh`) failed with "No content
+ * file matches", and so did the root-relative path a person types next
+ * (Round 6, school persona).
+ * `*` stays within one folder, `**` crosses any number of folders. Both
+ * flags repeat. A pattern that matches no source file is an error, raised
+ * before anything is spent — a typo must not turn into "nothing happened".
+ */
+
+import { compilePattern } from './no-translate.js';
+
+/**
+ * @typedef {object} FileScope
+ * @property {(label: string) => boolean} includes - Is this file in the run?
+ * @property {(label: string) => boolean} retranslates - Translate it fresh?
+ * @property {() => void} assertAllMatched - Throw if a pattern matched nothing
+ * @property {boolean} limitsFiles - True when --files was given
+ * @property {string[]} retranslatePatterns
+ */
+
+function toList(value) {
+  if (value == null) return [];
+  return (Array.isArray(value) ? value : [value])
+    .flatMap(v => String(v).split(','))
+    .map(v => v.trim().replace(/^\.\//, '').replace(/\\/g, '/'))
+    .filter(Boolean);
+}
+
+/**
+ * Build the run's file scope from CLI args. Returns null when neither flag
+ * was given (the common case costs nothing).
+ *
+ * @param {object} cliArgs
+ * @param {{ rootPrefix?: string }} [options] - rootPrefix: the content
+ *   directory relative to the project root ("newsletter"); a pattern then
+ *   also matches `<rootPrefix>/<label>`
+ * @returns {FileScope|null}
+ */
+export function compileFileScope(cliArgs = {}, { rootPrefix = '' } = {}) {
+  const filesPatterns = toList(cliArgs.files);
+  const retranslatePatterns = toList(cliArgs.retranslate);
+  if (filesPatterns.length === 0 && retranslatePatterns.length === 0) return null;
+
+  const compile = (patterns) => patterns.map(p => ({ pattern: p, test: compilePattern(p, '/'), hits: 0 }));
+  const files = compile(filesPatterns);
+  const retranslate = compile(retranslatePatterns);
+
+  const rawPrefix = String(rootPrefix || '').replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+  const prefix = rawPrefix === '.' ? '' : rawPrefix;
+  const matchAny = (list, label) => {
+    const rel = label.replace(/\\/g, '/');
+    const forms = [rel.split('/')];
+    if (prefix) forms.push(`${prefix}/${rel}`.split('/'));
+    let hit = false;
+    for (const m of list) {
+      if (forms.some(segments => m.test(segments))) { m.hits++; hit = true; }
+    }
+    return hit;
+  };
+
+  return {
+    limitsFiles: files.length > 0,
+    retranslatePatterns,
+    retranslates: (label) => matchAny(retranslate, label),
+    // A --retranslate file is always in the run, even outside --files. Both
+    // lists are consulted every time: a short-circuit here left every
+    // --retranslate pattern (= `--redo files:<glob> --fresh`) with zero hits
+    // when no --files was given, and the run failed "No content file
+    // matches" for a file that exists (Round 6, school persona).
+    includes: (label) => {
+      const inRetranslate = matchAny(retranslate, label);
+      const inFiles = files.length === 0 || matchAny(files, label);
+      return inFiles || inRetranslate;
+    },
+    assertAllMatched() {
+      const dead = [...files, ...retranslate].filter(m => m.hits === 0).map(m => m.pattern);
+      if (dead.length > 0) {
+        const e = new Error(
+          `No content file matches ${dead.map(p => JSON.stringify(p)).join(', ')}. ` +
+          `Patterns match the paths sync prints, e.g. "docs/intro.md" or "posts/**"${prefix ? `, or the path from the project root ("${prefix}/…")` : ''}. Nothing was translated.`);
+        e.code = 'CHAMPOLLION_NO_FILE_MATCH';
+        throw e;
+      }
+    },
+  };
+}

package/lib/flatten.js

@@ -32,9 +32,57 @@ function flattenKeys(obj, prefix = '') {
   return keys;
 }
 
+/** An i18next plural key: `<base>[_ordinal]_<category>` (lib/plurals.js). */
+const PLURAL_KEY_RE = /^(.+?)(_ordinal)?_(zero|one|two|few|many|other)$/;
+/** CLDR's order of the plural categories. */
+const PLURAL_ORDER = ['zero', 'one', 'two', 'few', 'many', 'other'];
+
+/**
+ * Put `key` into `obj`. An existing key keeps its place. A NEW plural form
+ * (`count_many`) goes beside its siblings (`count_one`, `count_other`, same
+ * base, cardinal or ordinal alike) in CLDR order — before the first sibling
+ * whose category comes after it, else after the last sibling — and nothing
+ * else in the object moves. Any other new key goes at the end, as before.
+ *
+ * WHY: `verify`'s repair for a missing `count_many` appended it after
+ * `count_other`, so French and Spanish files ordered their plural keys
+ * differently (Round 10, i18next persona). A fresh file is written in the
+ * expansion's CLDR order; a restored form now lands where it would have been.
+ *
+ * Works on a nested object's level (the leaf name) and on a flat map
+ * (`cart.count_many` — the base includes the dotted path).
+ *
+ * @param {object} obj
+ * @param {string} key
+ * @param {*} value
+ */
+function assignInOrder(obj, key, value) {
+  if (Object.prototype.hasOwnProperty.call(obj, key)) { obj[key] = value; return; }
+  const m = PLURAL_KEY_RE.exec(key);
+  if (!m) { obj[key] = value; return; }
+  const rank = PLURAL_ORDER.indexOf(m[3]);
+  const keys = Object.keys(obj);
+  let at = -1; // insert before keys[at]
+  let lastSibling = -1;
+  for (let i = 0; i < keys.length; i++) {
+    const s = PLURAL_KEY_RE.exec(keys[i]);
+    if (!s || s[1] !== m[1] || !!s[2] !== !!m[2]) continue;
+    if (PLURAL_ORDER.indexOf(s[3]) > rank) { at = i; break; }
+    lastSibling = i;
+  }
+  if (at < 0 && lastSibling < 0) { obj[key] = value; return; }
+  const insertAt = at >= 0 ? at : lastSibling + 1;
+  if (insertAt >= keys.length) { obj[key] = value; return; }
+  const entries = Object.entries(obj);
+  entries.splice(insertAt, 0, [key, value]);
+  for (const k of keys) delete obj[k];
+  for (const [k, v] of entries) obj[k] = v;
+}
+
 /**
  * Set a value in a nested object using a dot-notation path.
- * Creates intermediate objects as needed.
+ * Creates intermediate objects as needed. A new plural form is placed among
+ * its siblings in CLDR order (assignInOrder); other new keys go at the end.
  *
  * @param {object} obj - Target nested object
  * @param {string} dotPath - Dot-notation path like "pages.about.title"
@@ -49,7 +97,36 @@ function setNestedValue(obj, dotPath, value) {
     }
     current = current[parts[i]];
   }
-  current[parts[parts.length - 1]] = value;
+  assignInOrder(current, parts[parts.length - 1], value);
+}
+
+/**
+ * Delete a dot-notation path from a nested object. Parents are left in
+ * place (they usually hold sibling keys); a parent left EMPTY by the delete
+ * is removed too, so no `{}` husk is written back to the locale file.
+ *
+ * @param {object} obj - Target nested object
+ * @param {string} dotPath - Dot-notation path like "cart.item_one"
+ * @returns {boolean} True when a value was removed
+ */
+function deleteNestedValue(obj, dotPath) {
+  const parts = dotPath.split('.');
+  const chain = [obj];
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const next = current[parts[i]];
+    if (typeof next !== 'object' || next === null || Array.isArray(next)) return false;
+    chain.push(next);
+    current = next;
+  }
+  const leaf = parts[parts.length - 1];
+  if (!Object.prototype.hasOwnProperty.call(current, leaf)) return false;
+  delete current[leaf];
+  for (let i = chain.length - 1; i > 0; i--) {
+    if (Object.keys(chain[i]).length > 0) break;
+    delete chain[i - 1][parts[i - 1]];
+  }
+  return true;
 }
 
-export { flattenKeys, setNestedValue };
+export { flattenKeys, setNestedValue, deleteNestedValue, assignInOrder };

package/lib/flutter-locales.js

@@ -0,0 +1,124 @@
+/**
+ * flutter-locales.js — does Flutter's own UI text cover a target locale?
+ *
+ * `flutter gen-l10n` builds the app's messages from the ARB files sync
+ * writes, but Material and Cupertino widgets (date pickers, "Back",
+ * "Cancel", text direction) take their own text from flutter_localizations
+ * (GlobalMaterialLocalizations, GlobalCupertinoLocalizations,
+ * GlobalWidgetsLocalizations), which cover a fixed list of languages. An app
+ * whose supportedLocales include one outside that list — a private-use code
+ * such as `qaa`, most low-resource languages — fails at runtime ("No
+ * MaterialLocalizations found") unless it adds a fallback delegate (Round
+ * 11, hospital persona: neither init nor the Flutter docs said so).
+ *
+ * The list is Flutter's own, read from the Flutter SDK on this machine
+ * (FLUTTER_ROOT, or the `flutter` on PATH): one
+ * `packages/flutter_localizations/lib/src/l10n/material_<locale>.arb` file
+ * per covered locale. Nothing here guesses it: without an SDK, a private-use
+ * code is reported as uncovered (no list can hold one) and every other code
+ * is reported as unchecked, with where to read the rule.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPrivateUseCode } from './registers.js';
+
+/** Where the CLI's Flutter section explains the fallback delegate. */
+export const FLUTTER_LOCALES_DOC = 'https://champollion.dev/docs/integrations/frameworks#flutter-locales-outside-flutters-own-list';
+
+/** The directory of Flutter's material_<locale>.arb files, from an SDK root. */
+const L10N_DIR = path.join('packages', 'flutter_localizations', 'lib', 'src', 'l10n');
+
+/**
+ * The Flutter SDK root on this machine: FLUTTER_ROOT, else the directory
+ * above the `bin/` of the first `flutter` on PATH (symlinks resolved).
+ *
+ * @param {object} [env=process.env]
+ * @returns {string|null}
+ */
+export function findFlutterSdk(env = process.env) {
+  const isSdk = (root) => !!root && fs.existsSync(path.join(root, L10N_DIR));
+  if (env.FLUTTER_ROOT && isSdk(env.FLUTTER_ROOT)) return env.FLUTTER_ROOT;
+  for (const dir of String(env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const name of process.platform === 'win32' ? ['flutter.bat', 'flutter'] : ['flutter']) {
+      const exe = path.join(dir, name);
+      let real;
+      try { real = fs.realpathSync(exe); } catch { continue; }
+      const root = path.dirname(path.dirname(real));
+      if (isSdk(root)) return root;
+    }
+  }
+  return null;
+}
+
+/**
+ * The language codes Flutter's Material localizations cover, read from the
+ * SDK: `material_pt_BR.arb` → "pt". null when no SDK is found.
+ *
+ * @param {object} [env=process.env]
+ * @returns {{ languages: Set<string>, from: string }|null}
+ */
+export function flutterMaterialLanguages(env = process.env) {
+  const root = findFlutterSdk(env);
+  if (!root) return null;
+  const dir = path.join(root, L10N_DIR);
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return null; }
+  const languages = new Set();
+  for (const n of names) {
+    const m = /^material_([A-Za-z]{2,3})(?:_[A-Za-z0-9]+)*\.arb$/.exec(n);
+    if (m) languages.add(m[1].toLowerCase());
+  }
+  return languages.size > 0 ? { languages, from: dir } : null;
+}
+
+/** "pt_BR" / "pt-BR" → "pt". */
+function languageOf(code) {
+  return String(code).split(/[-_]/)[0].toLowerCase();
+}
+
+/**
+ * Which ARB target locales Flutter's own widget text does not cover.
+ *
+ * @param {string[]} codes - Target locales as the ARB files name them
+ * @param {object} [env=process.env]
+ * @returns {{ uncovered: string[], unchecked: string[], from: string|null }}
+ *   uncovered: outside Flutter's list (or private-use); unchecked: no SDK here to check against
+ */
+export function flutterUncoveredLocales(codes, env = process.env) {
+  const list = flutterMaterialLanguages(env);
+  const uncovered = [];
+  const unchecked = [];
+  for (const code of codes) {
+    // A private-use code (qaa–qtz) is in no published list.
+    if (isPrivateUseCode(code)) uncovered.push(code);
+    else if (!list) unchecked.push(code);
+    else if (!list.languages.has(languageOf(code))) uncovered.push(code);
+  }
+  return { uncovered, unchecked, from: list ? list.from : null };
+}
+
+/**
+ * The line(s) init and sync print for ARB targets: what to add for a locale
+ * Flutter does not cover, or — with no SDK here — that it was not checked.
+ * Empty when every target is covered.
+ *
+ * @param {string[]} codes
+ * @param {object} [env=process.env]
+ * @returns {Array<{ level: 'warn'|'info', text: string }>}
+ */
+export function flutterLocaleLines(codes, env = process.env) {
+  const { uncovered, unchecked, from } = flutterUncoveredLocales(codes, env);
+  const lines = [];
+  if (uncovered.length > 0) {
+    const basis = from ? `checked against ${from}` : 'a private-use code is in no list';
+    lines.push({ level: 'warn', text: `Flutter: its own Material/Cupertino widget text (GlobalMaterialLocalizations) does not cover ${uncovered.join(', ')} (${basis}). `
+      + `An app with ${uncovered.length > 1 ? 'these locales' : 'this locale'} in supportedLocales fails at runtime without a fallback delegate for it — add one: ${FLUTTER_LOCALES_DOC}` });
+  }
+  if (unchecked.length > 0) {
+    lines.push({ level: 'info', text: `Flutter: no Flutter SDK found here (FLUTTER_ROOT, or flutter on PATH), so ${unchecked.join(', ')} ${unchecked.length > 1 ? 'were' : 'was'} not checked against `
+      + `the languages Flutter's own widget text covers (GlobalMaterialLocalizations). A language outside that list needs a fallback delegate: ${FLUTTER_LOCALES_DOC}` });
+  }
+  return lines;
+}