euparliamentmonitor 0.9.13 → 0.9.14

package/scripts/validate-brief-translations.js

@@ -23,10 +23,12 @@
  *      adopted-text IDs like `TA-10-2026-0160`) must appear in the translation
  *      whenever they appear in the source.
  *   6. **Heading parity**             — H1/H2/H3 heading counts must match
- *      the source closely (H1 must match exactly; H2/H3 may differ by at most
- *      `HEADING_TOLERANCE`). LLMs frequently collapse or skip subsections,
- *      and this gate catches that without flagging legitimate small
- *      reformattings.
+ *      the source closely. H1 must match exactly (one per brief by style
+ *      guide). H2 must match exactly (`H2_TOLERANCE = 0`): each `##` heading
+ *      is a major section and dropping or merging one is the single most
+ *      common AI failure mode. H3 may differ by at most `H3_TOLERANCE` (1)
+ *      to allow legitimate sub-bullet fusion. The legacy `HEADING_TOLERANCE`
+ *      export is preserved as an alias for `H3_TOLERANCE`.
  *   7. **Mermaid block parity**       — every ```` ```mermaid ```` block in the
  *      source must appear at least once in the translation. Mermaid syntax
  *      is a machine-readable fixed token; dropping a diagram silently breaks
@@ -142,16 +144,25 @@ const FIXED_TOKEN_PATTERNS_GLOBAL = Object.freeze(
 );
 
 /**
- * Tolerance (in absolute count) for H2/H3 heading-count drift between the
- * source and the translation. H1 must match exactly: there is only one H1
- * per brief by convention.
+ * Tolerance (in absolute count) for H3 heading-count drift between the
+ * source and the translation.
  *
- * Why a small non-zero floor? Translators sometimes legitimately fuse two
- * very short sub-bullets into one paragraph, or split a long H3 into two
- * for readability in CJK scripts where dense text harms scanability. A
- * tolerance of 1 absorbs that without letting whole sections disappear.
+ * - **H1**: hard zero — every brief has exactly one H1 by style guide.
+ * - **H2**: hard zero (see `H2_TOLERANCE` below). H2 is a major section;
+ *   silently dropping or merging one is the single most common AI failure
+ *   mode and the validator must catch it even when the dropped section
+ *   contains no `FIXED_TOKEN_PATTERNS` matches to flag separately.
+ * - **H3**: tolerance of 1. Translators sometimes legitimately fuse two
+ *   very short sub-bullets into one paragraph, or split a long H3 into two
+ *   for readability in CJK scripts where dense text harms scanability.
+ *
+ * `HEADING_TOLERANCE` is preserved as a backward-compatible alias for
+ * `H3_TOLERANCE` so existing consumers (tests, downstream tooling that
+ * imports the constant) keep working.
  */
-export const HEADING_TOLERANCE = 1;
+export const H2_TOLERANCE = 0;
+export const H3_TOLERANCE = 1;
+export const HEADING_TOLERANCE = H3_TOLERANCE;
 
 /**
  * Pattern that matches a fenced ```mermaid block opener (case-insensitive).
@@ -188,6 +199,78 @@ export function countMermaidBlocks(text) {
   return countGlobal(text, MERMAID_OPENER);
 }
 
+/**
+ * Extract H2 section titles from markdown text. Mirrors the shape returned
+ * by `scripts/discover-untranslated-briefs.js#extractH2Titles` so the
+ * validator can produce a precise "likely-dropped section" diagnostic when
+ * the heading-parity gate fires.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function extractH2Titles(text) {
+  const lines = text.split('\n');
+  const out = [];
+  for (const line of lines) {
+    const match = /^##\s+(\S.*)$/.exec(line);
+    if (match) out.push(match[1].trim());
+  }
+  return out;
+}
+
+/**
+ * Compute the set of source H2 titles that have no fuzzy match in the
+ * translation. We do NOT require translated titles to be identical — they
+ * are localised — but every source H2 should map to *some* translation
+ * H2. We treat two titles as "potentially matched" when they share any
+ * fixed-token prefix (`IMF`, `WEO`, `TA-…`, `data-vintage="…"`) or when
+ * the translation has exactly the same count of H2s. The output is purely
+ * advisory: the gate itself still fires on count mismatch.
+ *
+ * Heuristic: a source title is reported as "likely dropped" only when
+ *   (a) it contains at least one FIXED_TOKEN_PATTERNS match, AND
+ *   (b) no translation title contains that same token, AND
+ *   (c) the H2 count mismatch is exactly 1 (so we're confident a single
+ *       section vanished rather than a wholesale restructure).
+ *
+ * @param {string[]} sourceTitles
+ * @param {string[]} targetTitles
+ * @returns {string[]}
+ */
+function detectLikelyDroppedH2s(sourceTitles, targetTitles) {
+  if (sourceTitles.length - targetTitles.length !== 1) return [];
+  const dropped = [];
+  // Count, per FIXED TOKEN, how many source H2 titles contain it vs how
+  // many target H2 titles contain it. When a source H2 contains a token
+  // whose translation-side count is strictly smaller, that source H2 is
+  // very likely the dropped section.
+  for (const title of sourceTitles) {
+    const tokens = [];
+    for (const re of FIXED_TOKEN_PATTERNS) {
+      const m = new RegExp(re.source).exec(title);
+      if (m) tokens.push(m[0]);
+    }
+    if (tokens.length === 0) continue;
+    let lostToken = false;
+    for (const tok of tokens) {
+      const sourceHits = sourceTitles.filter((t) => t.includes(tok)).length;
+      const targetHits = targetTitles.filter((t) => t.includes(tok)).length;
+      if (targetHits < sourceHits) {
+        lostToken = true;
+        break;
+      }
+    }
+    if (lostToken) dropped.push(title);
+  }
+  // If the heuristic flagged multiple, prefer the *last-occurring* source
+  // title with a lost token — the second-of-two duplicate-titled section
+  // is the prototypical regression (run #25983007788). When no token
+  // signal at all is available, we return [] so the message stays clean
+  // rather than guessing.
+  if (dropped.length > 1) return [dropped[dropped.length - 1]];
+  return dropped;
+}
+
 
 /** Count exact token occurrences returned by one fixed-token pattern. */
 function countMatches(text, regex) {
@@ -199,6 +282,16 @@ function countMatches(text, regex) {
   return counts;
 }
 
+/**
+ * Quote one shell argument for safe copy/paste in POSIX shells.
+ *
+ * @param {string} arg
+ * @returns {string}
+ */
+function shellQuote(arg) {
+  return `'${String(arg).replace(/'/g, `'\"'\"'`)}'`;
+}
+
 /**
  * Aggregate a violation list into a `{ key: count }` map for the validator
  * report. Items with falsy values at `key` are skipped so the filename-gate
@@ -397,6 +490,8 @@ export function validateTranslation(translationPath, repoRoot) {
       }
     }
     if (missingTokens.length > 0) {
+      const relQuoted = shellQuote(rel);
+      const siblingGlobQuoted = shellQuote(`${path.posix.dirname(rel)}/executive-brief_*.md`);
       violations.push({
         translationPath: rel,
         sourcePath: sourceRel,
@@ -404,19 +499,45 @@ export function validateTranslation(translationPath, repoRoot) {
         gate: 'fixed-token-preservation',
         message:
           `Translation is missing exact ${reSingle} token(s): ${missingTokens.join(', ')} ` +
-          `— proper noun / data-vintage identifiers MUST be preserved verbatim`,
+          `— proper noun / data-vintage identifiers MUST be preserved verbatim. ` +
+          `Self-check before flush: \`node scripts/validate-brief-translations.js --paths ${relQuoted}\` ` +
+          `(or \`--paths ${siblingGlobQuoted}\` to validate every sibling). ` +
+          `Dutch example: \`IMF\` stays \`IMF\` (never \`IMV\`); \`WEO\` stays \`WEO\` ` +
+          `(never \`Wereldwijde Economische Vooruitzichten\`).`,
       });
     }
   }
 
-  // Gate 6 — heading parity. H1 must match exactly (briefs have exactly one
-  // by style guide); H2/H3 may drift by HEADING_TOLERANCE in absolute count.
+  // Gate 6 — heading parity. H1 and H2 must match exactly (briefs have
+  // exactly one H1 by style guide; each H2 is a major section that must
+  // round-trip). H3 may drift by H3_TOLERANCE in absolute count.
   for (const level of [1, 2, 3]) {
     const sourceCount = countHeadings(sourceText, level);
     if (sourceCount === 0) continue;
     const targetCount = countHeadings(targetText, level);
-    const tolerance = level === 1 ? 0 : HEADING_TOLERANCE;
+    let tolerance;
+    if (level === 1) tolerance = 0;
+    else if (level === 2) tolerance = H2_TOLERANCE;
+    else tolerance = H3_TOLERANCE;
     if (Math.abs(sourceCount - targetCount) > tolerance) {
+      let detail = '';
+      if (level === 2) {
+        // Surface the actual H2 titles so reviewers/agents can pinpoint
+        // which section was dropped — regression hardening from run
+        // #25983007788 where 13 sibling translations identically dropped
+        // `## IMF Economic Context — May 2026 Update` and the validator
+        // report only said "8 vs 7 H2".
+        const sourceTitles = extractH2Titles(sourceText);
+        const targetTitles = extractH2Titles(targetText);
+        const dropped = detectLikelyDroppedH2s(sourceTitles, targetTitles);
+        const sourceList = sourceTitles.map((t) => `"${t}"`).join(', ');
+        detail = ` Source H2 titles: [${sourceList}].`;
+        if (dropped.length > 0) {
+          detail +=
+            ` Likely dropped: [${dropped.map((t) => `"${t}"`).join(', ')}].` +
+            ` Re-translate the missing section and keep its FIXED TOKEN(S) verbatim.`;
+        }
+      }
       violations.push({
         translationPath: rel,
         sourcePath: sourceRel,
@@ -424,7 +545,8 @@ export function validateTranslation(translationPath, repoRoot) {
         gate: 'heading-parity',
         message:
           `Translation has ${targetCount} H${level} heading(s); source has ${sourceCount} ` +
-          `(tolerance ±${tolerance}). Whole subsections appear to be missing or merged.`,
+          `(tolerance ±${tolerance}). Whole subsections appear to be missing or merged.` +
+          detail,
       });
     }
   }
@@ -451,6 +573,24 @@ export function validateTranslation(translationPath, repoRoot) {
   return violations;
 }
 
+/**
+ * Expand a list of paths that may contain glob patterns into resolved file paths.
+ * Uses Node's built-in fs.globSync (Node 22+) for any entry containing `*` or `?`.
+ */
+export function expandPathGlobs(rawPaths, repoRoot) {
+  const expanded = [];
+  for (const p of rawPaths) {
+    const resolved = path.resolve(repoRoot, p);
+    if (/[*?]/.test(resolved)) {
+      const matches = fs.globSync(resolved);
+      expanded.push(...matches);
+    } else {
+      expanded.push(resolved);
+    }
+  }
+  return expanded;
+}
+
 /** Run validation against a list of translation paths. */
 export function runValidation(translationPaths, repoRoot, { quiet = false } = {}) {
   const allViolations = [];
@@ -476,7 +616,7 @@ export function runValidation(translationPaths, repoRoot, { quiet = false } = {}
 export function main(argv) {
   const opts = parseArgs(argv);
   const paths = opts.paths.length > 0
-    ? opts.paths.map((p) => path.resolve(opts.repoRoot, p))
+    ? expandPathGlobs(opts.paths, opts.repoRoot)
     : findAllTranslations(opts.repoRoot);
 
   const violations = runValidation(paths, opts.repoRoot, { quiet: opts.quiet });