champollion 0.3.3 → 0.4.0

package/lib/commands/submit.js

@@ -13,7 +13,7 @@
  *   dataset · resource · method · human-service · external-result · card-correction
  *
  * Interactive wizard when stdin is a TTY; fully scriptable via flags otherwise
- * (--type + --values/--field + --attest, or --yes). See `champollion submit --help`.
+ * (--type + --values/--field + --attest, or --yes). See `champollion network submit --help`.
  *
  * Exit codes: 0 = URL produced (or cancelled); 1 = invalid/incomplete request.
  */
@@ -29,6 +29,7 @@ import {
   resolveType,
   repoBaseFromRepository,
   validateSubmission,
+  normalizeSubmissionValues,
   buildIssueUrl,
   buildSubmissionRecord,
 } from '../submit.mjs';
@@ -181,7 +182,7 @@ async function run(args, cwd) {
       return 0;
     }
     console.log('');
-    console.log('  Submission types (champollion submit --type <key>):');
+    console.log('  Submission types (champollion network submit --type <key>):');
     console.log('');
     SUBMISSION_TYPES.forEach((t, i) => {
       console.log(`    ${i + 1}. ${t.key} — ${t.label}`);
@@ -209,7 +210,7 @@ async function run(args, cwd) {
   } else {
     type = resolveType(args.type);
     if (!type) {
-      output.error('Choose a submission type with --type (run `champollion submit --list`).');
+      output.error('Choose a submission type with --type (run `champollion network submit --list`).');
       return 1;
     }
     values = gatherFromFlags(type, args);
@@ -220,12 +221,16 @@ async function run(args, cwd) {
   if (!v.ok) {
     console.error('[ERR] Cannot build this submission:');
     for (const e of v.errors) console.error(`      • ${e}`);
-    console.error('');
-    console.error('      The compliance attestation is required. Re-run and confirm it');
-    console.error('      (interactively, or pass --attest with the other fields).');
+    if (v.errors.some((e) => e.startsWith('you must confirm'))) {
+      console.error('');
+      console.error('      The compliance attestation is required. Re-run and confirm it');
+      console.error('      (interactively, or pass --attest with the other fields).');
+    }
     return 1;
   }
 
+  // Language pairs go out one way: source>target, one per line (eng-crk in, eng>crk out).
+  values = normalizeSubmissionValues(type, values);
   const issueUrl = buildIssueUrl({ type, values, repoBase });
   const generatedAt = new Date().toISOString();
   const record = buildSubmissionRecord({ type, values, repoBase, generatedAt });
@@ -279,10 +284,10 @@ async function run(args, cwd) {
 
 function showHelp() {
   console.log(`
-  champollion submit — Propose an entry for the Champollion index (review-gated)
+  champollion network submit — Propose an entry for the Champollion index (review-gated)
 
   USAGE
-    champollion submit [options]
+    champollion network submit [options]
 
   DESCRIPTION
     Gather the fields for a submission and print a PRE-FILLED GitHub issue URL
@@ -316,15 +321,15 @@ function showHelp() {
     "${ATTESTATION_TEXT}"
 
   EXAMPLES
-    champollion submit                                   # interactive wizard
-    champollion submit --list                            # see the types
+    champollion network submit                                   # interactive wizard
+    champollion network submit --list                            # see the types
     # A dataset submission, fully from flags:
-    champollion submit --yes --type dataset --attest \\
+    champollion network submit --yes --type dataset --attest \\
       --field dataset-name="GlobalVoices eng-amh" \\
       --field pairs=eng-amh --field license=CC-BY-4.0 \\
       --field source-url=https://globalvoices.org
     # An external result, with a saved local copy:
-    champollion submit --yes --type external-result --attest --out ./submission.json \\
+    champollion network submit --yes --type external-result --attest --out ./submission.json \\
       --values '{"system-name":"NLLB-200","pairs":"eng-crk","dataset":"FLORES-200","metric":"chrF++","score":"28.4","citation":"https://arxiv.org/abs/2207.04672"}'
   `);
 }

package/lib/commands/sync.js

@@ -7,6 +7,7 @@
  */
 
 import { runSync } from '../sync.js';
+import { shutdownMethods } from '../translate.js';
 import { output } from '../output.js';
 
 /**
@@ -20,8 +21,9 @@ import { output } from '../output.js';
  *       totalProcessed > 0`) returned 0 here, so a `sync` wired into a
  *       pre-deploy hook went green while silently shipping English
  *       fallbacks. Any failure with zero progress must be loud.
- *   2 — partial: some keys translated but others failed, OR verification
- *       found errors. The run did real work but isn't clean.
+ *   2 — partial: some keys translated but others failed (or were held
+ *       back: refused before by the same method, so not re-sent), OR
+ *       verification found errors. The run did real work but isn't clean.
  *       ALSO used for a --max-cost abort: the pre-run estimate exceeded the
  *       cap (or was unknowable — unknown ≠ free), so the sync deliberately
  *       stopped BEFORE any API call. Not catastrophic (nothing broke,
@@ -29,7 +31,8 @@ import { output } from '../output.js';
  *
  * Pure and total (never throws) so it can be unit-tested directly.
  *
- * @param {{ totalProcessed?: number, totalFailed?: number, verifyErrors?: number, maxCostAborted?: boolean } | null | undefined} result
+ * @param {{ totalProcessed?: number, totalFailed?: number, totalHeld?: number, contentTranslated?: number, contentFailed?: number,
+ *   contentHeldBack?: number, contentRefused?: number, verifyErrors?: number, maxCostAborted?: boolean } | null | undefined} result
  * @returns {number} exit code
  */
 function computeExitCode(result) {
@@ -38,16 +41,34 @@ function computeExitCode(result) {
   // --max-cost abort: deliberate pre-run stop, exit 2 by documented contract.
   if (result.maxCostAborted) return 2;
 
-  const processed = result.totalProcessed || 0;
-  const failed = result.totalFailed || 0;
+  // A key named for a redo that matches nothing (a typo, a msgid that only
+  // exists with a context): the repair asked for did not happen — exit 1,
+  // never the 0 of a run that "did" nothing.
+  if (Array.isArray(result.unmatchedKeys) && result.unmatchedKeys.length > 0) return 1;
+
+  // Content files count alongside keys: a run where every content file
+  // failed is a failure; one where some failed is partial.
+  const processed = (result.totalProcessed || 0) + (result.contentTranslated || 0);
+  const failed = (result.totalFailed || 0) + (result.contentFailed || 0);
   const verifyErrors = result.verifyErrors || 0;
+  // Keys held back (refused before by this method — lib/locale-state.js):
+  // not translated, so not a clean pass, but nothing failed anew. The same
+  // for Markdown blocks and front-matter fields (lib/content-refusals.js):
+  // held back, or refused by the quality gate this run and left as the
+  // '[EN] ' last resort.
+  // A plural message left without a form the language uses for ordinary
+  // counts (filled with the "other" form, marked in a gettext catalog) is
+  // incomplete in the same way.
+  const held = (result.totalHeld || 0) + (result.contentHeldBack || 0) + (result.contentRefused || 0)
+    + (result.totalPluralGaps || 0);
 
   // Catastrophic: failures with no successful work. A fully-failed sync
   // (bad key, every locale errored) must never exit 0.
   if (failed > 0 && processed === 0) return 1;
 
-  // Partial: real work done but something failed, or files didn't verify.
-  if (failed > 0 || verifyErrors > 0) return 2;
+  // Partial: real work done but something failed or was held back, or
+  // files didn't verify.
+  if (failed > 0 || held > 0 || verifyErrors > 0) return 2;
 
   return 0;
 }
@@ -81,6 +102,9 @@ async function run(args, cwd) {
       return 1;
     }
     throw err;
+  } finally {
+    // Stop the Python bridges external-method pairs started for this run.
+    await shutdownMethods();
   }
 
   return computeExitCode(result);

package/lib/commands/tm.js

@@ -27,11 +27,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
-import { loadTM, saveTM, tmSize, pruneTM, TM_DIR, TM_FILENAME } from '../tm.js';
+import { loadTM, saveTM, tmSize, pruneTM, describeMethodKey, TM_DIR, TM_FILENAME } from '../tm.js';
 import { resolveConfig } from '../config.js';
 import { resolveRuntime } from '../sync.js';
 import { seedTMFromExisting } from '../tm-seed.js';
-import { output } from '../output.js';
+import { output, localTimestamp } from '../output.js';
 
 /**
  * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
@@ -220,6 +220,8 @@ function runStats(args, cwd) {
 
   // Timestamps from metadata
   const created = tm._meta?.created || 'unknown';
+  // JSON keeps the stored (UTC) date for compatibility, plus the full ISO
+  // timestamps; the human report prints local time with the zone named.
   const createdDate = created !== 'unknown' ? created.split('T')[0] : 'unknown';
 
   // Find newest entry timestamp
@@ -277,6 +279,8 @@ function runStats(args, cwd) {
       sizeBytes: stat.size,
       created: createdDate,
       lastEntry: newestDate,
+      createdAt: created !== 'unknown' ? created : null,
+      lastEntryAt: newest || null,
       byLocale,
       unknownLocale: unknownCount,
     }, null, 2));
@@ -286,18 +290,20 @@ function runStats(args, cwd) {
   output.raw('\n  Translation Memory — .champollion/tm.json\n');
   output.raw(`  Entries:      ${entryCount.toLocaleString()}`);
   output.raw(`  File size:    ${sizeStr}`);
-  output.raw(`  Created:      ${createdDate}`);
-  output.raw(`  Last entry:   ${newestDate}`);
+  output.raw(`  Created:      ${created !== 'unknown' ? localTimestamp(created) : 'unknown'}`);
+  output.raw(`  Last entry:   ${newest ? localTimestamp(newest) : 'unknown'}`);
 
   if (sortedLocales.length > 0 || unknownCount > 0) {
     output.raw('\n  By locale:');
 
+    // One line per locale, then what made its entries — method, model and
+    // register in words (the raw cache key "local|stub-1|formal-vous|" was
+    // printed here before; lib/tm.js describeMethodKey).
     for (const [locale, stats] of sortedLocales) {
-      const methodParts = Object.entries(stats.methods)
-        .sort((a, b) => b[1] - a[1])
-        .map(([m, count]) => `${m}: ${count}`);
-      const methodStr = methodParts.length > 0 ? `  (${methodParts.join(', ')})` : '';
-      output.raw(`    ${locale.padEnd(6)} ${String(stats.total).padStart(5)} entries${methodStr}`);
+      output.raw(`    ${locale.padEnd(6)} ${String(stats.total).padStart(5)} entries`);
+      for (const [m, count] of Object.entries(stats.methods).sort((a, b) => b[1] - a[1])) {
+        output.raw(`    ${''.padEnd(6)} ${String(count).padStart(5)}  ${describeMethodKey(m)}`);
+      }
     }
 
     if (unknownCount > 0) {
@@ -438,7 +444,7 @@ async function runPrune(args, cwd) {
     }
     try {
       // Case-sensitive, no flags: banned-term patterns are usually
-      // case-shaped ("OCAP" vs a word that merely contains "ocap").
+      // case-shaped ("NASA" vs a word that merely contains "nasa").
       // Encode any case-insensitivity in the pattern itself ([Cc]…).
       matching = new RegExp(matchingRaw);
     } catch (err) {

package/lib/commands/verify.js

@@ -6,14 +6,21 @@
  * success and keys being wrong in fact.
  *
  * Exit code 1 if errors found (CI-gate compatible).
- * --warn-only exits 0 regardless.
+ * --strict exits 1 on warnings too (a source echo, a plural form the
+ * translation did not supply, two locales with identical text, a
+ * translation made from an older source text) — for a CI that must not pass
+ * them. --warn-only exits 0 regardless.
  *
  * This runs the same checks that sync's post-sync verification uses,
  * but can be invoked independently for CI pipelines or manual auditing.
+ *
+ * --pair en:fr (comma-separated) verifies only those pairs' locales — the
+ * same scoping `sync --pair` gives its post-sync verification. An unknown
+ * pair fails loud, exactly as it does for sync.
  */
 
 import { resolveConfig } from '../config.js';
-import { verifyLocales } from '../verify.js';
+import { verifyLocales, localesForPairFlag } from '../verify.js';
 import { output } from '../output.js';
 
 /**
@@ -27,12 +34,29 @@ async function run(args, cwd) {
   if (args.json) output.setMode('json');
   else if (args.quiet) output.setMode('quiet');
 
+  if (args.strict && args['warn-only']) {
+    output.error('--strict (fail on warnings) and --warn-only (never fail) contradict each other — pick one.');
+    return 1;
+  }
   const config = resolveConfig(args, cwd);
-  const { errors } = await verifyLocales(config, cwd);
+  let locales = null;
+  if (args.pair) {
+    try {
+      locales = localesForPairFlag(config, args.pair, { cwd });
+    } catch (err) {
+      output.error(err.message);
+      return 1;
+    }
+  }
+  // --strict: the summary line itself says a warning fails the check.
+  const { errors, warnings } = await verifyLocales(config, cwd, { locales, strict: !!args.strict && !args['warn-only'] });
 
   if (errors > 0 && !args['warn-only']) {
     return 1;
   }
+  if (args.strict && warnings > 0) {
+    return 1;
+  }
   return 0;
 }
 

package/lib/commands/wrap.js

@@ -13,11 +13,12 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveConfig } from '../config.js';
+import { resolveConfig, autoDetectLanguages } from '../config.js';
+import { discoverLocaleLayout } from '../locale-layout.js';
 import { detectFramework, walkDir } from '../lint.js';
 import {
   checkGitClean, createBackup, restoreFromBackup,
-  processFile, generateDiff, addKeysToLocales,
+  processFile, generateDiff, addKeysToLocales, wrapUnsupportedReason,
 } from '../autofix.js';
 import { output } from '../output.js';
 
@@ -54,6 +55,15 @@ async function run(args, cwd) {
   const framework = detectFramework(cwd);
   const minLength = parseInt(args['min-length'] || 2, 10);
 
+  // Decide WHERE extracted keys go before any source file is rewritten — a
+  // wrap that rewrote components to t('…') and then could not store the
+  // keys would leave the app showing raw key names.
+  const destination = resolveWrapDestination(config, cwd);
+  if (destination.error) {
+    output.error(destination.error);
+    return 1;
+  }
+
   output.raw(`\n  champollion wrap${isDry ? ' (dry run)' : ''}`);
   output.raw(`  Framework: ${framework.name}`);
   output.raw('');
@@ -117,9 +127,11 @@ async function run(args, cwd) {
 
   // Add extracted keys to locale files (only if not dry-run)
   if (!isDry && allFixes.length > 0) {
-    const targetLocales = config.languages || [];
-    addKeysToLocales(allFixes, config.localesDir, config.inputLocale, targetLocales);
-    output.info(`Added ${allFixes.length} key(s) to locale files`);
+    const written = addKeysToLocales(allFixes, destination.source, destination.targets);
+    output.info(`Added ${allFixes.length} key(s) to ${destination.source.rel}`
+      + (written.targets > 0 ? ` and ${written.targets} target file(s) (as [EN] placeholders for the next sync)` : ''));
+  } else if (isDry && allFixes.length > 0) {
+    output.info(`Would add ${allFixes.length} key(s) to ${destination.source.rel}`);
   }
 
   output.raw('');
@@ -135,4 +147,50 @@ async function run(args, cwd) {
   return 0;
 }
 
+/**
+ * The locale files `wrap` writes extracted keys into: the source file (one
+ * per flat project; the `defaultNamespace` file — or the only file — of a
+ * folder-per-locale project) and the matching file of every configured
+ * target locale.
+ *
+ * @param {object} config - Resolved config
+ * @param {string} cwd
+ * @returns {{ source?: object, targets?: object[], error?: string }}
+ */
+function resolveWrapDestination(config, cwd) {
+  if (config.format === 'docusaurus') {
+    return { error: 'wrap writes t() keys into key-value locale files; Docusaurus translates through <Translate> and `docusaurus write-translations` — wrap does not apply.' };
+  }
+  const layout = discoverLocaleLayout(config, { cwd });
+  let ns = '';
+  if (layout.namespaced) {
+    const namespaces = layout.sourceFiles.map(f => f.ns);
+    if (config.defaultNamespace) {
+      if (!namespaces.includes(config.defaultNamespace)) {
+        return { error: `"defaultNamespace" is "${config.defaultNamespace}", but the source locale has no such file (namespaces: ${namespaces.join(', ') || 'none'}).` };
+      }
+      ns = config.defaultNamespace;
+    } else if (namespaces.length === 1) {
+      ns = namespaces[0];
+    } else {
+      return { error: `This project has ${namespaces.length} namespace files (${namespaces.join(', ') || 'none'}). `
+        + 'Set "defaultNamespace" in champollion.config.json to choose the file wrap adds keys to.' };
+    }
+  }
+  const source = layout.sourceFiles.find(f => f.ns === ns) || layout.sourceFiles[0];
+  // Flutter ARB and gettext catalogs cannot hold t('dotted.key') keys —
+  // refuse before any component is rewritten.
+  const refusal = source ? wrapUnsupportedReason(source) : null;
+  if (refusal) return { error: refusal };
+  if (!source || !fs.existsSync(source.path)) {
+    return { error: `Source locale file not found: ${source ? source.path : layout.display} — wrap needs it to store the extracted keys.` };
+  }
+  // Configured targets, or — like sync — the ones on disk when none are.
+  const languages = Object.keys(config.resolvedLanguages || {}).length > 0
+    ? config.resolvedLanguages
+    : autoDetectLanguages(config);
+  const targetCodes = Object.keys(languages).filter(c => c !== config.inputLocale);
+  return { source, targets: targetCodes.map(code => layout.fileFor(code, ns)) };
+}
+
 export { run };