champollion 0.3.3

package/lib/commands/wrap.js

@@ -0,0 +1,138 @@
+/**
+ * Command: wrap
+ *
+ * Auto-wraps hardcoded user-facing strings in t() calls.
+ * Includes safety gates:
+ *   1. Git-clean check (skip in dry-run)
+ *   2. Automatic backup to .champollion-backup/
+ *   3. Diff preview before each file write
+ *   4. --undo support to restore from backup
+ *
+ * After wrapping, adds the extracted keys to locale files.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveConfig } from '../config.js';
+import { detectFramework, walkDir } from '../lint.js';
+import {
+  checkGitClean, createBackup, restoreFromBackup,
+  processFile, generateDiff, addKeysToLocales,
+} from '../autofix.js';
+import { output } from '../output.js';
+
+/**
+ * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
+ * @param {string} cwd - Working directory
+ * @returns {Promise<number>} Exit code (0 = success, 1 = error)
+ */
+async function run(args, cwd) {
+  // Gate: Undo mode — restore from backup and exit
+  if (args.undo) {
+    const { restored, errors } = restoreFromBackup(cwd);
+    if (errors.length > 0) {
+      for (const err of errors) output.error(err);
+      return 1;
+    }
+    output.ok(`Restored ${restored} file(s) from .champollion-backup/`);
+    return 0;
+  }
+
+  const isDry = !!args.dry;
+
+  // Gate: Git-clean check (skip in dry-run mode)
+  if (!isDry) {
+    const { clean, status } = checkGitClean(cwd);
+    if (!clean) {
+      output.error('Git working tree is not clean. Commit or stash first.');
+      output.raw(`     ${status.split('\n').slice(0, 5).join('\n     ')}`);
+      return 1;
+    }
+  }
+
+  const config = resolveConfig(args, cwd);
+  const framework = detectFramework(cwd);
+  const minLength = parseInt(args['min-length'] || 2, 10);
+
+  output.raw(`\n  champollion wrap${isDry ? ' (dry run)' : ''}`);
+  output.raw(`  Framework: ${framework.name}`);
+  output.raw('');
+
+  // Find source files
+  let sourceFiles = [];
+  const srcDir = args.src || null;
+  if (srcDir) {
+    sourceFiles = walkDir(path.resolve(cwd, srcDir), framework.extensions, ['node_modules', '.next', 'dist', 'build', '.git']);
+  } else {
+    for (const dir of framework.srcDirs) {
+      sourceFiles.push(...walkDir(path.resolve(cwd, dir), framework.extensions, ['node_modules', '.next', 'dist', 'build', '.git']));
+    }
+  }
+
+  if (sourceFiles.length === 0) {
+    output.info('No source files found to process.');
+    return 0;
+  }
+
+  // Gate: Backup (only if not dry-run)
+  if (!isDry) {
+    createBackup(sourceFiles, cwd);
+    output.info('Backup created at .champollion-backup/');
+  }
+
+  let totalFixes = 0;
+  let totalAmbiguous = 0;
+  const allFixes = [];
+
+  for (const filePath of sourceFiles) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const relPath = path.relative(cwd, filePath);
+
+    const { modified, fixes, ambiguous } = processFile(
+      content, framework.name, framework, minLength
+    );
+
+    if (fixes.length === 0 && ambiguous.length === 0) continue;
+
+    // Show diff for applied fixes
+    if (fixes.length > 0) {
+      const diff = generateDiff(content, modified, relPath);
+      if (diff) output.raw(diff);
+    }
+
+    // Report ambiguous cases that need human review
+    for (const item of ambiguous) {
+      output.warn(`${relPath}:${item.line} — "${item.text}" (${item.reason})`);
+    }
+
+    // Write only if not dry-run
+    if (!isDry && fixes.length > 0) {
+      fs.writeFileSync(filePath, modified, 'utf-8');
+    }
+
+    totalFixes += fixes.length;
+    totalAmbiguous += ambiguous.length;
+    allFixes.push(...fixes);
+  }
+
+  // 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`);
+  }
+
+  output.raw('');
+  output.ok(`${totalFixes} fix(es) applied${isDry ? ' (dry run)' : ''}`);
+  if (totalAmbiguous > 0) {
+    output.warn(`${totalAmbiguous} ambiguous case(s) flagged for review`);
+  }
+  if (!isDry && totalFixes > 0) {
+    output.raw('  Run `champollion wrap --undo` to revert');
+  }
+  output.raw('');
+
+  return 0;
+}
+
+export { run };

package/lib/commands/xliff.js

@@ -0,0 +1,327 @@
+/**
+ * Command: xliff
+ *
+ * Exports and imports XLIFF 1.2 files for professional translator review.
+ *
+ * Subcommands:
+ *   export   Generate a .xliff file from source + target locale files.
+ *   import   Merge reviewed translations from a .xliff file back into locale files.
+ *
+ * WHY THIS EXISTS:
+ *   XLIFF is the industry-standard exchange format between translation tools
+ *   and CAT (Computer-Assisted Translation) platforms. This command lets users:
+ *     1. Export translations for professional review in memoQ/SDL Trados/Phrase
+ *     2. Import reviewed translations back, then run sync to fill gaps
+ *     3. Integrate champollion into existing localization workflows
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveConfig } from '../config.js';
+import { exportXLIFF, importXLIFF } from '../xliff.js';
+import { compileNoTranslate } from '../no-translate.js';
+import { flattenKeys, setNestedValue } from '../flatten.js';
+import { readLocaleFile, writeLocaleFile, detectFormatFromDir, detectYAMLStyle, getExtension } from '../format.js';
+import { output } from '../output.js';
+
+/** Default output directory for exported XLIFF files */
+const XLIFF_DIR = '.champollion/xliff';
+
+/**
+ * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
+ * @param {string} cwd - Working directory
+ * @returns {Promise<number>} Exit code (0 = success, 1 = error)
+ */
+async function run(args, cwd) {
+  const sub = args._[1];
+
+  // --json: stdout carries exactly one JSON document. Quiet mode keeps the
+  // human raws off stdout; warnings/errors still reach stderr.
+  if (args.json) output.setMode('quiet');
+
+  if (!sub || sub === 'help') {
+    printUsage();
+    return 0;
+  }
+
+  if (sub === 'export') {
+    return runExport(args, cwd);
+  }
+
+  if (sub === 'import') {
+    return runImport(args, cwd);
+  }
+
+  output.error(`Unknown subcommand: "${sub}". Run "champollion xliff --help" for usage.`);
+  return 1;
+}
+
+// -----------------------------------------------------------------
+// xliff export
+// -----------------------------------------------------------------
+
+/**
+ * Export source + target locale as XLIFF 1.2.
+ *
+ * Reads the source locale and the specified target locale,
+ * generates XLIFF, and writes it to .champollion/xliff/<locale>.xliff
+ * (or a custom path via --out).
+ */
+function runExport(args, cwd) {
+  const locale = args.locale;
+  if (!locale) {
+    output.error('Missing required --locale flag. Example: champollion xliff export --locale fr');
+    return 1;
+  }
+
+  const config = resolveConfig(args, cwd);
+  const format = config.format !== 'auto'
+    ? config.format
+    : detectFormatFromDir(config.localesDir);
+  const ext = getExtension(format);
+
+  // Load source locale
+  const sourcePath = path.join(config.localesDir, `${config.inputLocale}${ext}`);
+  if (!fs.existsSync(sourcePath)) {
+    output.error(`Source locale file not found: ${sourcePath}`);
+    return 1;
+  }
+  const sourceRaw = readLocaleFile(sourcePath, format);
+  const sourceFlat = format === 'json' ? flattenKeys(sourceRaw) : { ...sourceRaw };
+
+  // Load target locale (may not exist yet — that's fine, all targets will be empty)
+  const targetPath = path.join(config.localesDir, `${locale}${ext}`);
+  let targetFlat = {};
+  if (fs.existsSync(targetPath)) {
+    const targetRaw = readLocaleFile(targetPath, format);
+    targetFlat = format === 'json' ? flattenKeys(targetRaw) : { ...targetRaw };
+  }
+
+  // Generate XLIFF
+  const xliff = exportXLIFF({
+    sourceLocale: config.inputLocale,
+    targetLocale: locale,
+    sourceFlat,
+    targetFlat,
+    original: `${config.inputLocale}${ext}`,
+    noTranslate: compileNoTranslate(config),
+  });
+
+  // Determine output path
+  const outDir = args.out || path.join(cwd, XLIFF_DIR);
+  const outPath = args.out
+    ? (args.out.endsWith('.xliff') ? args.out : path.join(args.out, `${locale}.xliff`))
+    : path.join(outDir, `${locale}.xliff`);
+
+  // Write
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, xliff, 'utf-8');
+
+  const keyCount = Object.keys(sourceFlat).filter(k => typeof sourceFlat[k] === 'string').length;
+  const translatedCount = Object.keys(targetFlat).filter(k =>
+    typeof targetFlat[k] === 'string' && targetFlat[k].length > 0
+  ).length;
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      command: 'xliff',
+      action: 'export',
+      locale,
+      path: outPath,
+      exported: keyCount,
+      translated: translatedCount,
+      pending: keyCount - translatedCount,
+    }, null, 2));
+    return 0;
+  }
+
+  output.raw(`\n  ✓ Exported XLIFF 1.2 for ${config.inputLocale} → ${locale}`);
+  output.raw(`    Keys:        ${keyCount}`);
+  output.raw(`    Translated:  ${translatedCount}`);
+  output.raw(`    Pending:     ${keyCount - translatedCount}`);
+  output.raw(`    Written to:  ${path.relative(cwd, outPath)}`);
+  output.raw('');
+  output.raw('  Send this file to your translator or open it in a CAT tool');
+  output.raw('  (memoQ, SDL Trados, Phrase, etc.). When reviewed, import it back:');
+  output.raw(`    champollion xliff import ${path.relative(cwd, outPath)}\n`);
+
+  return 0;
+}
+
+// -----------------------------------------------------------------
+// xliff import
+// -----------------------------------------------------------------
+
+/**
+ * Import reviewed translations from an XLIFF file back into the locale file.
+ *
+ * Reads the XLIFF, extracts target translations, and merges them
+ * into the corresponding locale file. Only keys present in the
+ * XLIFF are overwritten — existing translations for other keys
+ * are preserved.
+ */
+function runImport(args, cwd) {
+  const xliffPath = args._[2];
+  if (!xliffPath) {
+    output.error('Missing XLIFF file path. Example: champollion xliff import .champollion/xliff/fr.xliff');
+    return 1;
+  }
+
+  const resolvedPath = path.resolve(cwd, xliffPath);
+  if (!fs.existsSync(resolvedPath)) {
+    output.error(`XLIFF file not found: ${resolvedPath}`);
+    return 1;
+  }
+
+  const xliffContent = fs.readFileSync(resolvedPath, 'utf-8');
+  const { translations, metadata } = importXLIFF(xliffContent);
+
+  if (Object.keys(translations).length === 0) {
+    if (args.json) {
+      console.log(JSON.stringify({
+        command: 'xliff', action: 'import', locale: metadata.targetLocale || null,
+        path: resolvedPath, imported: 0, updated: 0, added: 0, unchanged: 0,
+        note: 'No translated entries found in the XLIFF file.',
+      }, null, 2));
+      return 0;
+    }
+    output.raw('\n  No translated entries found in the XLIFF file.');
+    output.raw('  Make sure the XLIFF contains <target> elements with content.\n');
+    return 0;
+  }
+
+  const locale = metadata.targetLocale;
+  if (!locale) {
+    output.error('Could not determine target locale from XLIFF metadata.');
+    output.error('The <file> element must have a target-language attribute.');
+    return 1;
+  }
+
+  const config = resolveConfig(args, cwd);
+  const format = config.format !== 'auto'
+    ? config.format
+    : detectFormatFromDir(config.localesDir);
+  const ext = getExtension(format);
+  const targetPath = path.join(config.localesDir, `${locale}${ext}`);
+
+  const dryRun = args.dry || false;
+
+  // Load existing target locale (or start fresh)
+  let existingFlat = {};
+  let existingRaw = {};
+  if (fs.existsSync(targetPath)) {
+    existingRaw = readLocaleFile(targetPath, format);
+    existingFlat = format === 'json' ? flattenKeys(existingRaw) : { ...existingRaw };
+  }
+
+  // Merge: XLIFF translations overwrite existing values
+  let updated = 0;
+  let added = 0;
+  for (const [key, value] of Object.entries(translations)) {
+    if (key in existingFlat) {
+      if (existingFlat[key] !== value) {
+        updated++;
+      }
+    } else {
+      added++;
+    }
+    existingFlat[key] = value;
+  }
+
+  const skipped = Object.keys(translations).length - updated - added;
+
+  if (dryRun) {
+    if (args.json) {
+      console.log(JSON.stringify({
+        command: 'xliff', action: 'import', dryRun: true, locale, path: targetPath,
+        imported: Object.keys(translations).length, updated, added, unchanged: skipped,
+      }, null, 2));
+      return 0;
+    }
+    output.raw(`\n  [DRY RUN] Would import ${Object.keys(translations).length} translations for ${locale}`);
+    output.raw(`    Updated:  ${updated} (changed from existing)`);
+    output.raw(`    Added:    ${added} (new keys)`);
+    output.raw(`    Unchanged: ${skipped}`);
+    output.raw(`    Target:   ${path.relative(cwd, targetPath)}\n`);
+    return 0;
+  }
+
+  // Write back
+  if (format === 'json') {
+    // Re-nest the flat map into JSON structure using setNestedValue
+    const nested = {};
+    for (const [key, value] of Object.entries(existingFlat)) {
+      setNestedValue(nested, key, value);
+    }
+    fs.writeFileSync(targetPath, JSON.stringify(nested, null, 2) + '\n', 'utf-8');
+  } else {
+    // TOML/YAML — write the merged flat map back through the exact same
+    // writer sync uses (lib/format.js writeLocaleFile), so an imported file
+    // keeps the serialization style of a synced project. YAML needs the
+    // style probe sync performs on the SOURCE locale file (Hugo plural
+    // sub-keys vs standard nesting); fall back to the target file when the
+    // source is missing.
+    let yamlStyle = null;
+    if (format === 'yaml') {
+      const sourcePath = path.join(config.localesDir, `${config.inputLocale}${ext}`);
+      const stylePath = fs.existsSync(sourcePath) ? sourcePath
+        : (fs.existsSync(targetPath) ? targetPath : null);
+      yamlStyle = stylePath ? detectYAMLStyle(fs.readFileSync(stylePath, 'utf-8')) : null;
+    }
+    writeLocaleFile(targetPath, existingFlat, format, existingFlat, yamlStyle);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      command: 'xliff', action: 'import', dryRun: false, locale, path: targetPath,
+      imported: Object.keys(translations).length, updated, added, unchanged: skipped,
+    }, null, 2));
+    return 0;
+  }
+
+  output.raw(`\n  ✓ Imported ${Object.keys(translations).length} translations for ${locale}`);
+  output.raw(`    Updated:    ${updated} (changed from existing)`);
+  output.raw(`    Added:      ${added} (new keys)`);
+  output.raw(`    Unchanged:  ${skipped}`);
+  output.raw(`    Written to: ${path.relative(cwd, targetPath)}\n`);
+
+  return 0;
+}
+
+// -----------------------------------------------------------------
+// Usage
+// -----------------------------------------------------------------
+
+function printUsage() {
+  output.raw(`
+  champollion xliff — XLIFF 1.2 export/import for professional review
+
+  SUBCOMMANDS
+    export    Generate a .xliff file for a target locale
+    import    Merge reviewed .xliff translations back into locale files
+
+  OPTIONS
+    --locale <code>   Target locale for export (required for export)
+    --out <path>      Custom output path or directory (export)
+    --dry             Preview import without writing files
+    --json            Single JSON document output (export/import)
+    --config <path>   Path to config file
+
+  Import writes back in the project's locale format (JSON, TOML, or YAML)
+  using the same serializers sync uses.
+
+  WORKFLOW
+    1. Export:  champollion xliff export --locale fr
+    2. Review:  Send .champollion/xliff/fr.xliff to translator or CAT tool
+    3. Import:  champollion xliff import .champollion/xliff/fr.xliff
+    4. Sync:    champollion sync  (fills remaining gaps)
+
+  EXAMPLES
+    champollion xliff export --locale fr
+    champollion xliff export --locale ja --out ./review/
+    champollion xliff import .champollion/xliff/fr.xliff
+    champollion xliff import ./reviewed.xliff --dry
+  `);
+}
+
+export { run };

package/lib/commercial-eligibility.js

@@ -0,0 +1,235 @@
+/**
+ * commercial-eligibility.js — the ONE answer to "may this method be routed to
+ * in a COMMERCIAL lane?", enforced at routing time.
+ *
+ * WHY THIS EXISTS. `commercialReady` was declared in three places that had
+ * already drifted: the cross-runtime SSOT (`shared/method-registry.json`),
+ * a hardcoded table in `lib/provenance.js`, and each method loader's own
+ * `getProvenance()`. LibreTranslate was `AGPL-3.0` + `commercialReady: true`
+ * in two of them and `false` in the SSOT — i.e. the AGPL boundary CLAUDE.md
+ * calls a never-cross rule was crossable by reading the wrong table. This
+ * module makes the SSOT win everywhere and makes the answer enforceable
+ * instead of advisory.
+ *
+ * THE RULES, in precedence order:
+ *
+ *   1. **The shared registry wins.** If `shared/method-registry.json` has an
+ *      entry for the method (by canonical key OR `cli_name`), its
+ *      `commercialReady` is the answer. Nothing overrides it upward — a
+ *      plugin cannot declare itself commercial-ready past an SSOT `false`.
+ *   2. **A plugin may only ever restrict.** `pluginProvenance.commercialReady
+ *      === false` blocks even when the registry says true (a coached plugin
+ *      can carry NC coaching data the engine knows nothing about).
+ *   3. **Methods the registry deliberately does not model** — CLI-only
+ *      pseudo-methods with no cross-runtime adapter — are declared in
+ *      CLI_ONLY below, each with its reason.
+ *   4. **Unknown is INELIGIBLE.** No registry entry, no declaration, no
+ *      plugin provenance → not routable commercially. Fail-safe, matching
+ *      `license-gate.mjs`'s doctrine for sources ("an unknown / unstated /
+ *      mixed source is treated as RESTRICTED").
+ *
+ * SCOPE. This gates the COMMERCIAL lane only. Champollion's default lane is
+ * non-commercial, where NC and copyleft engines are perfectly usable — that
+ * is the open project, and nothing here restricts it. Same orthogonality
+ * `license-gate.mjs` already applies to corpora: use context is a descriptor,
+ * not a single bucket.
+ *
+ * @module commercial-eligibility
+ */
+
+import { manifestEntries, cliNameFor } from './method-manifest.js';
+import { USE_CONTEXTS } from './license-gate.mjs';
+
+/**
+ * Methods with no entry in the shared registry, because they are CLI-only
+ * constructs rather than engines with a cross-runtime adapter.
+ *
+ * Every entry states WHY. An engine that belongs in the registry must go in
+ * the registry — this table is not a bypass for it.
+ */
+const CLI_ONLY = {
+  // Plain LLM translation through the user's own provider key. The engine
+  // itself carries no external data dependency; the provider's ToS governs,
+  // and every LLM provider in the registry is commercialReady.
+  'llm-coached': {
+    eligible: true,
+    license: 'Provider ToS (per LLM provider)',
+    reason: 'the method carries no data dependency of its own — its COACHING '
+      + 'data does, and that rides pluginProvenance (rule 2), which can only '
+      + 'restrict',
+  },
+
+  // Human-in-the-loop review. No external resource at all.
+  'human-review': {
+    eligible: true,
+    license: 'n/a',
+    reason: 'no external resource — human review of output already produced',
+  },
+
+  // Points at a remote champollion-serve endpoint. Whatever is BEHIND it is
+  // declared by the plugin manifest, so with no declaration there is nothing
+  // to stand on.
+  api: {
+    eligible: false,
+    license: 'unknown (declared by the plugin manifest)',
+    reason: 'a remote endpoint\'s provenance is only knowable from its plugin '
+      + 'manifest — supply one declaring commercialReady, or route it in the '
+      + 'non-commercial lane',
+  },
+
+  // Arbitrary user-supplied Python method directory.
+  external: {
+    eligible: false,
+    license: 'unknown (user-supplied plugin)',
+    reason: 'a user-supplied plugin\'s dependencies are unknown to us',
+  },
+
+  // The Plains Cree FST pipeline: AGPL FST invoked as a separate tool, plus
+  // the Wolvengrey dictionary, which is index-only and permanently
+  // non-redistributable (founder ruling 2026-07-19).
+  'fst-gated': {
+    eligible: false,
+    license: 'AGPL-3.0-or-later + PROPRIETARY dictionary',
+    reason: 'depends on an AGPL FST and a proprietary dictionary under a '
+      + 'pending agreement',
+  },
+};
+
+/**
+ * Look the method up in the shared registry by canonical key or CLI alias.
+ *
+ * @param {string} methodName
+ * @returns {{ name: string, entry: object } | null} null when the registry is
+ *   absent (standalone package with no bundled shared/) or the name is unknown
+ */
+function registryEntryFor(methodName) {
+  for (const [name, entry] of Object.entries(manifestEntries())) {
+    if (name === methodName || cliNameFor(name, entry) === methodName) {
+      return { name, entry };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve whether a method may be routed to commercially.
+ *
+ * Pure and offline — reads the bundled registry only. Never throws; callers
+ * that want an exception use assertRoutable().
+ *
+ * @param {string} methodName - CLI method name or canonical registry key
+ * @param {object} [opts]
+ * @param {object|null} [opts.pluginProvenance] - The plugin manifest's own
+ *   provenance declaration, when the pair config carries one. May only restrict.
+ * @returns {{ eligible: boolean, source: string, license: string|null,
+ *   reason: string }} `source` is where the verdict came from, so a report can
+ *   cite it: 'registry' | 'cli-only' | 'plugin' | 'unknown'
+ */
+export function resolveCommercialEligibility(methodName, { pluginProvenance = null } = {}) {
+  const pluginBlocks = !!pluginProvenance
+    && typeof pluginProvenance === 'object'
+    && pluginProvenance.commercialReady === false;
+
+  const found = registryEntryFor(methodName);
+  if (found) {
+    const { name, entry } = found;
+    const eligible = entry.commercialReady === true && !pluginBlocks;
+    let reason;
+    if (pluginBlocks) {
+      reason = 'the installed plugin declares itself not commercial-ready';
+    } else if (entry.commercialReady === true) {
+      reason = `cleared in the shared method registry (${name})`;
+    } else {
+      reason = `not commercial-ready in the shared method registry (${name})`;
+    }
+    return {
+      eligible,
+      source: pluginBlocks ? 'plugin' : 'registry',
+      license: entry.license || null,
+      reason,
+    };
+  }
+
+  const declared = CLI_ONLY[methodName];
+  if (declared) {
+    const eligible = declared.eligible && !pluginBlocks;
+    return {
+      eligible,
+      source: pluginBlocks ? 'plugin' : 'cli-only',
+      license: declared.license,
+      reason: pluginBlocks
+        ? 'the installed plugin declares itself not commercial-ready'
+        : declared.reason,
+    };
+  }
+
+  // Rule 4. A plugin declaring itself ready is NOT enough to clear an
+  // otherwise-unknown method — that would let any manifest self-certify.
+  return {
+    eligible: false,
+    source: 'unknown',
+    license: null,
+    reason: `"${methodName}" has no recorded commercial eligibility — unknown `
+      + 'methods are treated as restricted',
+  };
+}
+
+/**
+ * Error thrown when a commercial route is refused. Carries the structured
+ * verdict so an API layer can render it without re-deriving anything.
+ */
+export class CommercialRouteBlockedError extends Error {
+  /**
+   * @param {string} methodName
+   * @param {{eligible:boolean, source:string, license:string|null, reason:string}} verdict
+   */
+  constructor(methodName, verdict) {
+    super(
+      `Method "${methodName}" is not cleared for the commercial lane: `
+      + `${verdict.reason}`
+      + (verdict.license ? ` (license: ${verdict.license})` : '')
+      + '. Route it in the non-commercial lane, or use a method whose license '
+      + 'permits commercial use (`champollion recommend <src> <tgt> '
+      + '--use commercial` lists them).'
+    );
+    this.name = 'CommercialRouteBlockedError';
+    this.methodName = methodName;
+    this.verdict = verdict;
+  }
+}
+
+/**
+ * Enforcement point. Throws when the lane is commercial and the method is not
+ * cleared; returns the verdict otherwise.
+ *
+ * The non-commercial lane is the default and is never blocked here — NC and
+ * copyleft engines are legitimate there, which is the whole point of the open
+ * project.
+ *
+ * @param {string} methodName
+ * @param {object} [opts]
+ * @param {('commercial'|'non-commercial')} [opts.useContext='non-commercial']
+ * @param {object|null} [opts.pluginProvenance]
+ * @returns {{eligible:boolean, source:string, license:string|null, reason:string}}
+ * @throws {CommercialRouteBlockedError}
+ */
+export function assertRoutable(methodName, { useContext = USE_CONTEXTS.NON_COMMERCIAL, pluginProvenance = null } = {}) {
+  const verdict = resolveCommercialEligibility(methodName, { pluginProvenance });
+  if (useContext === USE_CONTEXTS.COMMERCIAL && !verdict.eligible) {
+    throw new CommercialRouteBlockedError(methodName, verdict);
+  }
+  return verdict;
+}
+
+/**
+ * Convenience boolean for report surfaces that only need the answer.
+ *
+ * @param {string} methodName
+ * @param {object} [opts]
+ * @returns {boolean}
+ */
+export function isCommercialEligible(methodName, opts = {}) {
+  return resolveCommercialEligibility(methodName, opts).eligible;
+}
+
+export { CLI_ONLY as CLI_ONLY_ELIGIBILITY };