champollion 0.3.3

package/lib/tags/bcp47.js

@@ -0,0 +1,202 @@
+/**
+ * bcp47.js — parse a language tag into its parts.
+ *
+ * WHY WE PARSE RATHER THAN SPLIT ON HYPHENS
+ *   Because the parts are not positional. `zh-Hans-CN`, `zh-CN`, `zh-Hans` and
+ *   `zh-x-pirate` all have a different second element, and the only way to know
+ *   which is which is by SHAPE: four letters is a script, two letters or three
+ *   digits is a region, `x-` opens private use. Code that assumes position gets
+ *   `sr-Latn` right and `sr-RS` wrong, which is the kind of bug that surfaces
+ *   as one language quietly rendering in the wrong script.
+ *
+ * WELL-FORMEDNESS, NOT VALIDITY
+ *   RFC 5646 draws the distinction and so does this file. Well-formed means the
+ *   tag has legal shape. Valid means every subtag is registered with IANA. This
+ *   parser answers the first question only; the resolver answers the second by
+ *   looking the subtags up in the atlas, which is where the registry lives.
+ *
+ *   Keeping them apart matters: a well-formed tag we cannot resolve is a
+ *   language we may simply not index yet, and reporting it as malformed would
+ *   blame the caller for our own coverage gap.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+ */
+
+/** RFC 5646 2.2.9 — the irregular grandfathered tags, which match no grammar. */
+const IRREGULAR = new Set([
+  'en-gb-oed', 'i-ami', 'i-bnn', 'i-default', 'i-enochian', 'i-hak',
+  'i-klingon', 'i-lux', 'i-mingo', 'i-navajo', 'i-pwn', 'i-tao', 'i-tay',
+  'i-tsu', 'sgn-be-fr', 'sgn-be-nl', 'sgn-ch-de',
+]);
+
+const ALPHA = /^[a-z]+$/;
+const ALPHANUM = /^[a-z0-9]+$/;
+const DIGIT = /^[0-9]+$/;
+
+/**
+ * @typedef {object} ParsedTag
+ * @property {string} input        the tag as given
+ * @property {boolean} wellFormed
+ * @property {string|null} language   primary language subtag, lower-cased
+ * @property {string[]} extlangs
+ * @property {string|null} script     title-cased, as BCP 47 recommends
+ * @property {string|null} region     upper-cased
+ * @property {string[]} variants
+ * @property {Record<string,string[]>} extensions  keyed by singleton
+ * @property {string[]} privateUse    subtags after `x-`
+ * @property {boolean} grandfathered
+ * @property {string|null} problem    why it is not well-formed, in words
+ */
+
+/**
+ * Parse a BCP 47 language tag.
+ *
+ * Never throws: a malformed tag is a fact about the input, and callers need to
+ * report it rather than catch it.
+ *
+ * @param {string} input
+ * @returns {ParsedTag}
+ */
+export function parseTag(input) {
+  const base = {
+    input,
+    wellFormed: false,
+    language: null,
+    extlangs: [],
+    script: null,
+    region: null,
+    variants: [],
+    extensions: {},
+    privateUse: [],
+    grandfathered: false,
+    problem: null,
+  };
+
+  if (typeof input !== 'string' || input === '') {
+    return { ...base, problem: 'empty tag' };
+  }
+  // BCP 47 tags are case-insensitive; casing is presentational only.
+  const lower = input.toLowerCase();
+  if (lower.length > 255) {
+    return { ...base, problem: 'tag longer than 255 characters' };
+  }
+  if (/[^a-z0-9-]/.test(lower)) {
+    return { ...base, problem: 'contains characters other than letters, digits and hyphen' };
+  }
+  if (lower.startsWith('-') || lower.endsWith('-') || lower.includes('--')) {
+    return { ...base, problem: 'empty subtag (leading, trailing or doubled hyphen)' };
+  }
+
+  if (IRREGULAR.has(lower)) {
+    return { ...base, wellFormed: true, grandfathered: true, language: null };
+  }
+
+  const parts = lower.split('-');
+  let i = 0;
+
+  // ── Whole-tag private use: `x-pirate`. Legal, and denotes no registered
+  //    language at all — which is exactly what a conlang code should say.
+  if (parts[0] === 'x') {
+    const sub = parts.slice(1);
+    if (!sub.length || sub.some((p) => !ALPHANUM.test(p) || p.length > 8)) {
+      return { ...base, problem: 'private-use tag needs 1-8 alphanumeric subtags after "x"' };
+    }
+    return { ...base, wellFormed: true, privateUse: sub };
+  }
+
+  // ── Primary language subtag ─────────────────────────────────────────────
+  const lang = parts[i];
+  if (!ALPHA.test(lang) || lang.length < 2 || lang.length > 8) {
+    return { ...base, problem: `"${lang}" is not a language subtag (2-8 letters)` };
+  }
+  const out = { ...base, language: lang };
+  i++;
+
+  // ── Extended language subtags: up to three, three letters each ──────────
+  // Only follow a 2-3 letter primary subtag, per the grammar.
+  while (
+    lang.length <= 3 && out.extlangs.length < 3
+    && parts[i] && parts[i].length === 3 && ALPHA.test(parts[i])
+  ) {
+    out.extlangs.push(parts[i]);
+    i++;
+  }
+
+  // ── Script: exactly four letters ────────────────────────────────────────
+  if (parts[i] && parts[i].length === 4 && ALPHA.test(parts[i])) {
+    out.script = parts[i][0].toUpperCase() + parts[i].slice(1);
+    i++;
+  }
+
+  // ── Region: two letters or three digits ─────────────────────────────────
+  if (parts[i]
+    && ((parts[i].length === 2 && ALPHA.test(parts[i]))
+      || (parts[i].length === 3 && DIGIT.test(parts[i])))) {
+    out.region = parts[i].toUpperCase();
+    i++;
+  }
+
+  // ── Variants: 5-8 alphanumerics, or a digit then three alphanumerics ────
+  while (parts[i]
+    && ((parts[i].length >= 5 && parts[i].length <= 8 && ALPHANUM.test(parts[i]))
+      || (parts[i].length === 4 && DIGIT.test(parts[i][0]) && ALPHANUM.test(parts[i])))) {
+    if (out.variants.includes(parts[i])) {
+      return { ...out, problem: `variant "${parts[i]}" repeated` };
+    }
+    out.variants.push(parts[i]);
+    i++;
+  }
+
+  // ── Extensions: a singleton (not x) then one or more 2-8 alphanumerics ──
+  while (parts[i] && parts[i].length === 1 && parts[i] !== 'x' && ALPHANUM.test(parts[i])) {
+    const singleton = parts[i];
+    if (out.extensions[singleton]) {
+      return { ...out, problem: `extension singleton "${singleton}" repeated` };
+    }
+    i++;
+    const sub = [];
+    while (parts[i] && parts[i].length >= 2 && parts[i].length <= 8 && ALPHANUM.test(parts[i])) {
+      sub.push(parts[i]);
+      i++;
+    }
+    if (!sub.length) {
+      return { ...out, problem: `extension "${singleton}" has no subtags` };
+    }
+    out.extensions[singleton] = sub;
+  }
+
+  // ── Private use, as a suffix ────────────────────────────────────────────
+  if (parts[i] === 'x') {
+    i++;
+    const sub = [];
+    while (parts[i] && parts[i].length >= 1 && parts[i].length <= 8 && ALPHANUM.test(parts[i])) {
+      sub.push(parts[i]);
+      i++;
+    }
+    if (!sub.length) return { ...out, problem: 'private-use "x" has no subtags' };
+    out.privateUse = sub;
+  }
+
+  if (i < parts.length) {
+    return { ...out, problem: `"${parts[i]}" is not a valid subtag in this position` };
+  }
+  return { ...out, wellFormed: true };
+}
+
+/**
+ * Re-assemble a parsed tag in BCP 47's recommended casing.
+ *
+ * @param {ParsedTag} t
+ * @returns {string}
+ */
+export function formatTag(t) {
+  if (t.grandfathered) return t.input.toLowerCase();
+  if (!t.language && t.privateUse.length) return `x-${t.privateUse.join('-')}`;
+  const parts = [t.language, ...t.extlangs];
+  if (t.script) parts.push(t.script);
+  if (t.region) parts.push(t.region);
+  parts.push(...t.variants);
+  for (const [singleton, sub] of Object.entries(t.extensions)) parts.push(singleton, ...sub);
+  if (t.privateUse.length) parts.push('x', ...t.privateUse);
+  return parts.join('-');
+}

package/lib/tags/resolve.js

@@ -0,0 +1,314 @@
+/**
+ * resolve.js — the ONE way anything in this repo turns a code into a language.
+ *
+ * THE PROBLEM IT EXISTS FOR
+ *   Every MT service publishes coverage in BCP 47 and every language card is
+ *   keyed by ISO 639-3, and the two do not agree about what a language is.
+ *   Google lists `zho`; nobody lists `cmn`. CLDR's rule is that Unicode
+ *   identifiers always use the macrolanguage for the predominant form, so the
+ *   services are conformant and we were the ones off-standard — bridging the
+ *   gap with eight hand-written routings that cited nothing.
+ *
+ *   The bridge is now data: three pinned registries, projected into a tag
+ *   index at build time. This module reads it and answers two questions.
+ *
+ * QUESTION ONE — WHAT LANGUAGE IS THIS CODE?
+ *   `resolveTag()`. It never guesses. Where a tag denotes a macrolanguage it
+ *   says so and reports what the registries say about a predominant member,
+ *   attributed; where they do not agree, or where several members fold in, it
+ *   reports that instead of picking. Norwegian has no cited predominant member
+ *   and `no` → `nob` is therefore visibly an editorial decision rather than a
+ *   fact hiding in a config file.
+ *
+ * QUESTION TWO — DOES THIS METHOD COVER THIS LANGUAGE?
+ *   `resolveCoverage()`. Coverage is stored at the granularity the METHOD
+ *   published and is never propagated down a macrolanguage. Instead the
+ *   relationship is named:
+ *
+ *     exact              the method lists this language
+ *     via-predominant    the method lists the macrolanguage, and both
+ *                        registries name this language as the member it denotes
+ *     via-macrolanguage  the method lists the macrolanguage, and this language
+ *                        is merely one of its members
+ *     none               nothing
+ *
+ *   The distinction is the whole point. OPUS-MT publishes coverage for `cre`,
+ *   and both CLDR and SIL name Woods Cree as the member `cre` denotes — so
+ *   Plains Cree gets `via-macrolanguage`, never `via-predominant`. That is a
+ *   weaker answer than a boolean and it is the true one, and it is what a Cree
+ *   speaker deciding whether to trust a translation actually needs to know.
+ *
+ * NOTHING HERE DECIDES WHAT TO DO ABOUT IT
+ *   A verdict is evidence, not a policy. Whether `via-macrolanguage` is good
+ *   enough to translate with is the caller's call, made under the caller's
+ *   flags, and recorded on the run — so a leaderboard row reads "crk via cre"
+ *   and can never silently become a `crk` score.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseTag } from './bcp47.js';
+
+/**
+ * The index is BUILD OUTPUT of `champollion atlas build`. Overridable so tests
+ * and the cutover can point at a freshly built one.
+ */
+export const TAG_INDEX_FILE =
+  process.env.CHAMPOLLION_TAG_INDEX
+  || path.join(import.meta.dirname, '..', '..', 'shared', 'tag-index.json');
+
+/** Verdicts, exported so callers branch on constants rather than strings. */
+export const ROUTE = Object.freeze({
+  EXACT: 'exact',
+  MACROLANGUAGE: 'macrolanguage',
+  AMBIGUOUS: 'ambiguous',
+  PRIVATE_USE: 'private-use',
+  UNKNOWN: 'unknown',
+  MALFORMED: 'malformed',
+});
+
+export const COVERAGE = Object.freeze({
+  EXACT: 'exact',
+  VIA_PREDOMINANT: 'via-predominant',
+  VIA_MACROLANGUAGE: 'via-macrolanguage',
+  NONE: 'none',
+});
+
+let cached = null;
+
+/**
+ * Load the tag index.
+ *
+ * Fails loudly and specifically when it is missing. A resolver that quietly
+ * degraded to "code in, code out" would look like it worked for the 90% of
+ * lookups where a code IS its own language, and be wrong on exactly the
+ * macrolanguages this module exists for.
+ *
+ * @param {string} [file]
+ */
+export function loadTagIndex(file = TAG_INDEX_FILE) {
+  if (cached && cached.file === file) return cached.index;
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `no tag index at ${file}. It is build output — run:\n`
+      + '    node cli/scripts/cldf/build-atlas.mjs\n'
+      + 'Resolving codes without it would silently succeed for individual languages '
+      + 'and silently mislead for every macrolanguage.',
+    );
+  }
+  const index = JSON.parse(fs.readFileSync(file, 'utf-8'));
+  if (!index.byTag || !index.languages) {
+    throw new Error(`${file} is not a tag index (no byTag/languages)`);
+  }
+  cached = { file, index };
+  return index;
+}
+
+/** Drop the memoised index. For tests that rebuild it between cases. */
+export function clearTagIndexCache() {
+  cached = null;
+}
+
+/**
+ * @typedef {object} Resolution
+ * @property {string} input
+ * @property {import('./bcp47.js').ParsedTag} tag
+ * @property {string|null} language      the atlas language ID, if one was found
+ * @property {string} route              one of ROUTE
+ * @property {string|null} scope         'individual' | 'macrolanguage'
+ * @property {object|null} predominant   {language, authorities[], agreement}
+ * @property {string|null} note          why there is no clean answer, in words
+ * @property {string[]} candidates       for an ambiguous tag, every reading
+ */
+
+/**
+ * Resolve one code or language tag.
+ *
+ * @param {string} input
+ * @param {object} [opts]
+ * @param {object} [opts.index]
+ * @returns {Resolution}
+ */
+export function resolveTag(input, { index = loadTagIndex() } = {}) {
+  // FLORES, NLLB and Meta's Omnilingual MT all identify a language as
+  // `lang_Script` — `arb_Arab`, `zho_Hans`, `crk_Cans`. That underscore is not
+  // BCP 47, which uses a hyphen, and `parseTag` is right to reject it: the
+  // parser answers "is this a well-formed language tag", and this is not one.
+  //
+  // But it is the dominant convention in machine translation, and rejecting it
+  // outright made the resolver useless for exactly the datasets this project
+  // reads. So the separator is normalised HERE, explicitly and reported, rather
+  // than by loosening the grammar — a caller gets the answer and is told the
+  // input was not a BCP 47 tag.
+  const flores = typeof input === 'string' && !input.includes('-') && input.includes('_')
+    ? input.replace(/_/g, '-')
+    : null;
+  const tag = parseTag(flores ?? input);
+  const base = {
+    input,
+    tag,
+    language: null,
+    route: ROUTE.UNKNOWN,
+    scope: null,
+    predominant: null,
+    note: flores
+      ? `read as "${flores}" — the input uses the FLORES/NLLB lang_Script `
+        + 'convention, which is not BCP 47'
+      : null,
+    candidates: [],
+  };
+
+  if (!tag.wellFormed) {
+    return { ...base, route: ROUTE.MALFORMED, note: tag.problem };
+  }
+  // A private-use tag denotes no registered language, which is exactly what a
+  // conlang code should say. Reporting it as unknown would invite a caller to
+  // treat it as a lookup failure and retry.
+  if (!tag.language && tag.privateUse.length) {
+    return {
+      ...base,
+      route: ROUTE.PRIVATE_USE,
+      note: `"${input}" is a private-use tag; it names no registered language`,
+    };
+  }
+  if (!tag.language) {
+    return {
+      ...base,
+      route: ROUTE.UNKNOWN,
+      note: tag.grandfathered
+        ? `"${input}" is a grandfathered tag with no primary language subtag`
+        : 'no primary language subtag',
+    };
+  }
+
+  const subtag = tag.language;
+  const ambiguous = index.ambiguousTags?.[subtag];
+  if (ambiguous && !ambiguous.resolvesTo) {
+    return {
+      ...base,
+      route: ROUTE.AMBIGUOUS,
+      note: ambiguous.reason,
+      candidates: ambiguous.alsoClaimedBy.map((c) => ({
+        language: c.language, sources: c.sources,
+      })),
+    };
+  }
+
+  const languageId = index.byTag[subtag] ?? null;
+  if (!languageId) {
+    return {
+      ...base,
+      route: ROUTE.UNKNOWN,
+      note: `"${subtag}" is well-formed but is not a code the atlas resolves`,
+    };
+  }
+
+  const entry = index.languages[languageId] ?? {};
+  if (entry.scope !== 'macrolanguage') {
+    return { ...base, language: languageId, route: ROUTE.EXACT, scope: 'individual' };
+  }
+
+  return {
+    ...base,
+    language: languageId,
+    route: ROUTE.MACROLANGUAGE,
+    scope: 'macrolanguage',
+    predominant: entry.predominant ?? null,
+    // Both facts can be true at once — `zho_Hans` is a FLORES-style tag AND a
+    // macrolanguage. Overwriting the first with the second lost the reading
+    // note on exactly the inputs that needed it most.
+    note: [
+      base.note,
+      entry.predominant
+        ? null
+        : entry.noPredominant
+          ?? `"${subtag}" is a macrolanguage and no registry names a member it denotes`,
+    ].filter(Boolean).join('; ') || null,
+  };
+}
+
+/**
+ * How does a method's published coverage relate to this language?
+ *
+ * @param {object} args
+ * @param {string} args.language        atlas language ID being asked about
+ * @param {Iterable<string>} args.covered  the codes the METHOD published, verbatim
+ * @param {object} [args.index]
+ * @returns {{verdict: string, via: string|null, authorities: string[], because: string}}
+ */
+export function resolveCoverage({ language, covered, index = loadTagIndex() }) {
+  const set = covered instanceof Set ? covered : new Set(covered);
+
+  if (set.has(language)) {
+    return {
+      verdict: COVERAGE.EXACT,
+      via: null,
+      authorities: [],
+      because: `the method lists "${language}" itself`,
+    };
+  }
+
+  const entry = index.languages[language];
+  const macro = entry?.macrolanguage ?? null;
+  if (!macro || !set.has(macro)) {
+    return {
+      verdict: COVERAGE.NONE, via: null, authorities: [],
+      because: macro
+        ? `the method lists neither "${language}" nor its macrolanguage "${macro}"`
+        : `the method does not list "${language}", which belongs to no macrolanguage`,
+    };
+  }
+
+  const macroEntry = index.languages[macro] ?? {};
+  const predominant = macroEntry.predominant ?? null;
+  if (predominant && predominant.language === language) {
+    return {
+      verdict: COVERAGE.VIA_PREDOMINANT,
+      via: macro,
+      authorities: predominant.authorities ?? [],
+      because: `the method lists the macrolanguage "${macro}", and `
+        + `${(predominant.authorities ?? []).join(' and ')} name "${language}" as the `
+        + 'member that tag denotes. The method still never said so itself.',
+    };
+  }
+
+  return {
+    verdict: COVERAGE.VIA_MACROLANGUAGE,
+    via: macro,
+    authorities: predominant ? predominant.authorities ?? [] : [],
+    because: predominant
+      ? `the method lists the macrolanguage "${macro}", but the registries name `
+        + `"${predominant.language}" as the member that tag denotes, not "${language}"`
+      : `the method lists the macrolanguage "${macro}", and no registry names which `
+        + 'of its members that tag denotes',
+  };
+}
+
+/**
+ * A one-line, human-readable account of a resolution — for CLI output, prompts
+ * and run records, so the same words appear everywhere a route is reported.
+ *
+ * @param {Resolution} r
+ */
+export function explainResolution(r) {
+  switch (r.route) {
+    case ROUTE.EXACT:
+      return `${r.input} → ${r.language}`;
+    case ROUTE.MACROLANGUAGE:
+      return r.predominant
+        ? `${r.input} → ${r.language} (a macrolanguage; ${r.predominant.authorities.join(' and ')} `
+          + `name ${r.predominant.language} as the language it denotes)`
+        : `${r.input} → ${r.language} (a macrolanguage; ${r.note})`;
+    case ROUTE.AMBIGUOUS:
+      return `${r.input} is ambiguous: ${r.candidates.map(
+        (c) => `${c.language} per ${c.sources.join(', ')}`,
+      ).join('; ')}`;
+    case ROUTE.PRIVATE_USE:
+      return `${r.input} is a private-use tag and names no registered language`;
+    case ROUTE.MALFORMED:
+      return `${r.input} is not a well-formed language tag: ${r.note}`;
+    default:
+      return `${r.input} does not resolve to a language the atlas knows`;
+  }
+}

package/lib/terminology.js

@@ -0,0 +1,111 @@
+/**
+ * Post-translation terminology enforcement — warns when dictionary terms
+ * were prompted but not used in the LLM output.
+ *
+ * WHY THIS EXISTS:
+ *   The coached method (llm-coached.js) injects a dictionary into the LLM
+ *   prompt: "REQUIRED TERMINOLOGY: dashboard → tableau de bord". But the LLM
+ *   is free to ignore it. Without verification, a user who carefully built
+ *   a dictionary has no way to know if their terms were actually applied.
+ *
+ * HOW IT WORKS:
+ *   After translation, this module scans each translated value to check
+ *   whether expected dictionary terms appear. If a source value contains
+ *   a dictionary source term (e.g., "dashboard") AND the translated value
+ *   does NOT contain the required translation (e.g., "tableau de bord"),
+ *   a violation is recorded.
+ *
+ *   Matching is case-insensitive substring search — the LLM might inflect
+ *   the term ("tableaux de bord" for plural), so exact match would be too
+ *   strict. Violations are warnings, not blocking errors.
+ *
+ * USAGE:
+ *   import { verifyTerminology } from './terminology.js';
+ *
+ *   const { violations } = verifyTerminology(translations, sourceFlat, dictionary);
+ *   if (violations.length > 0) {
+ *     console.warn(`[TERM] ${violations.length} term(s) may not have been applied`);
+ *   }
+ */
+
+/**
+ * Check whether required dictionary terms were used in translations.
+ *
+ * For each translated value:
+ *   1. Find which dictionary source terms appear in the corresponding source value
+ *   2. For each matching term, check if the required translation appears in the output
+ *   3. Record violations where the term was expected but not found
+ *
+ * @param {object} translations - key → translated value (LLM output)
+ * @param {object} sourceFlat - key → source value (English)
+ * @param {object} dictionary - source term → required translation
+ *   e.g., { "dashboard": "tableau de bord", "sign in": "se connecter" }
+ * @returns {{ violations: Array<{ key: string, term: string, expected: string, got: string }> }}
+ */
+function verifyTerminology(translations, sourceFlat, dictionary) {
+  const violations = [];
+
+  // Fast path: nothing to check
+  if (!dictionary || typeof dictionary !== 'object' || Object.keys(dictionary).length === 0) {
+    return { violations };
+  }
+
+  // Pre-lowercase dictionary entries for case-insensitive matching
+  const terms = Object.entries(dictionary).map(([src, tgt]) => ({
+    source: src,
+    sourceLower: src.toLowerCase(),
+    expected: tgt,
+    expectedLower: tgt.toLowerCase(),
+  }));
+
+  for (const [key, translated] of Object.entries(translations)) {
+    // Skip non-string values (defense-in-depth)
+    if (typeof translated !== 'string') continue;
+
+    const source = sourceFlat[key];
+    if (typeof source !== 'string') continue;
+
+    const sourceLower = source.toLowerCase();
+    const translatedLower = translated.toLowerCase();
+
+    for (const term of terms) {
+      // Step 1: Does the source value contain this dictionary source term?
+      if (!sourceLower.includes(term.sourceLower)) continue;
+
+      // Step 2: Does the translated value contain the required translation?
+      if (translatedLower.includes(term.expectedLower)) continue;
+
+      // Violation: term was expected but not found
+      violations.push({
+        key,
+        term: term.source,
+        expected: term.expected,
+        got: translated.length > 100 ? translated.slice(0, 100) + '…' : translated,
+      });
+    }
+  }
+
+  return { violations };
+}
+
+/**
+ * Log terminology violations in a structured, actionable format.
+ *
+ * Designed to sit alongside the existing [GATE] log output from validate.js.
+ * Violations are warnings — they don't block the translation from being written.
+ *
+ * @param {Array<{ key: string, term: string, expected: string, got: string }>} violations
+ * @param {string} pairKey - e.g., "en:fr"
+ */
+function logTermViolations(violations, pairKey) {
+  if (violations.length === 0) return;
+
+  console.error(`\n     [TERM] ${pairKey}: ${violations.length} dictionary term(s) may not have been applied:`);
+  for (const { key, term, expected, got } of violations) {
+    console.error(`            ⚠ "${key}": expected "${expected}" for term "${term}"`);
+    console.error(`              → got "${got}"`);
+  }
+  console.error('');
+}
+
+export { verifyTerminology, logTermViolations };