euparliamentmonitor 0.9.0 → 0.9.2

package/README.md

@@ -136,7 +136,7 @@ The published site is the audience-facing companion to this npm/TypeScript packa
 
 **MCP Server Integration**: The project uses the
 [European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server)
-v1.3.0 for accessing real EU Parliament data via the Model Context Protocol.
+v1.3.2 for accessing real EU Parliament data via the Model Context Protocol.
 
 - **MCP Server Status**: ✅ Fully operational — 60+ EP data tools available
   (feeds, direct lookups, analytical tools, intelligence correlation)
@@ -432,7 +432,7 @@ import type { ArticleCategory, LanguageCode } from 'euparliamentmonitor/types';
 
 ## 🔌 Data Sources
 
-**Primary — European Parliament MCP Server** ([Hack23/European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server) v1.3.0+, fully operational):
+**Primary — European Parliament MCP Server** ([Hack23/European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server) v1.3.2+, fully operational):
 
 - 🗳️ Plenary sessions, voting records, roll-call votes
 - 📜 Adopted texts, motions, resolutions, urgency files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -146,7 +146,7 @@
     "@playwright/test": "1.59.1",
     "@types/d3": "7.4.3",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "25.6.0",
+    "@types/node": "25.6.2",
     "@types/papaparse": "5.5.2",
     "@typescript-eslint/eslint-plugin": "8.59.2",
     "@typescript-eslint/parser": "8.59.2",
@@ -165,7 +165,7 @@
     "husky": "9.1.7",
     "jscpd": "4.0.9",
     "knip": "^6.7.0",
-    "lint-staged": "17.0.2",
+    "lint-staged": "17.0.3",
     "mermaid": "11.14.0",
     "papaparse": "5.5.3",
     "prettier": "3.8.3",
@@ -179,7 +179,7 @@
     "node": ">=26"
   },
   "dependencies": {
-    "european-parliament-mcp-server": "1.3.0",
+    "european-parliament-mcp-server": "1.3.2",
     "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
     "markdown-it-attrs": "^4.3.1",

package/scripts/aggregator/analysis-aggregator.js

@@ -550,30 +550,33 @@ export function aggregateAnalysisRun(options) {
     const analysisIndex = renderAnalysisIndex(includedArtifacts, manifestRelPath);
     const readerGuide = renderReaderIntelligenceGuide(emittedSections, includedArtifacts);
     // Deterministic 3–7 bullet "Key takeaways" block, harvested from the
-    // synthesis-summary / intelligence-assessment artifacts. Placed
-    // immediately after the Executive Brief so the reader gets the BLUF
-    // followed by a digest of the strongest findings before being handed
-    // off to the Reader Intelligence Guide and the deeper sections.
+    // synthesis-summary / intelligence-assessment artifacts. Sits between
+    // the Reader Intelligence Guide and the deep sections: the reader gets
+    // the BLUF (Executive Brief) → a navigation map (Reader Guide) → a
+    // bullet digest of the strongest findings (Key Takeaways) → the deep
+    // analysis. This is the order requested for reader UX so navigation
+    // is established before the reader commits to scanning takeaways.
     const keyTakeaways = buildKeyTakeaways({ runDir });
-    // TOC ordering reflects the rendered document:
+    // TOC ordering must match the rendered Markdown body 1:1. Order:
     // Executive Brief (already first in emittedSections via appendSection) →
-    // Key Takeaways (inserted right after the brief when present) →
-    // Reader Intelligence Guide → remaining sections → audit appendices.
+    // Reader Intelligence Guide (inserted right after the brief when present) →
+    // Key Takeaways (inserted right after the guide when present) →
+    // remaining sections → audit appendices.
     let postBriefIdx = emittedSections.length > 0 &&
         emittedSections[0]?.id === namespacedSectionId(execBriefSection?.id ?? '')
         ? 1
         : 0;
-    if (keyTakeaways) {
+    if (readerGuide) {
         emittedSections.splice(postBriefIdx, 0, {
-            id: KEY_TAKEAWAYS_SECTION_ID,
-            title: KEY_TAKEAWAYS_SECTION_TITLE,
+            id: READER_GUIDE_SECTION_ID,
+            title: READER_GUIDE_SECTION_TITLE,
         });
         postBriefIdx += 1;
     }
-    if (readerGuide) {
+    if (keyTakeaways) {
         emittedSections.splice(postBriefIdx, 0, {
-            id: READER_GUIDE_SECTION_ID,
-            title: READER_GUIDE_SECTION_TITLE,
+            id: KEY_TAKEAWAYS_SECTION_ID,
+            title: KEY_TAKEAWAYS_SECTION_TITLE,
         });
     }
     emittedSections.push({ id: TRADECRAFT_SECTION_ID, title: TRADECRAFT_SECTION_TITLE });
@@ -583,9 +586,8 @@ export function aggregateAnalysisRun(options) {
         '',
         ...execBriefMarkdown,
         '',
+        ...(readerGuide ? [readerGuide, ''] : []),
         ...(keyTakeaways ? [keyTakeaways, ''] : []),
-        readerGuide,
-        '',
         ...sectionMarkdown,
         '',
         provenance,

package/scripts/aggregator/article-generator.d.ts

@@ -19,7 +19,11 @@ export interface CliOptions {
      * is earlier are skipped.
      */
     readonly since?: string;
-    /** Languages to render (defaults to all 14). */
+    /**
+     * Languages to render. Defaults to all 14. The CLI always populates
+     * this with `[...ALL_LANGUAGES]` (the `--lang/--language` flags have
+     * been removed); programmatic callers (tests) can override it.
+     */
     readonly langs: readonly LanguageCode[];
     /** Output directory for HTML files (defaults to `news/`). */
     readonly outDir: string;
@@ -30,8 +34,11 @@ export interface CliOptions {
     /** Optional: override the auto-derived article description (single-run only). */
     readonly description?: string;
     /**
-     * When true, only the source Markdown is written (no HTML) — useful for
-     * upstream pipelines that translate first and then batch-render.
+     * When true, only the source Markdown is written (no HTML) — preserved
+     * for programmatic callers (tests) that need to skip HTML emission for
+     * speed. The CLI no longer exposes a flag for this and always sets
+     * `false`; every workflow-driven invocation emits HTML for all 14
+     * languages.
      */
     readonly markdownOnly: boolean;
 }
@@ -93,6 +100,24 @@ export declare function sanitizeRunSuffix(runId: string): string;
  * @returns Plain-text description, truncated to ≤300 characters
  */
 export declare function extractDefaultDescription(markdown: string): string;
+/**
+ * Insert the regenerated Reader Intelligence Guide HTML immediately after
+ * the Executive Brief section so the rendered article body matches the
+ * documented order (Executive Brief → Reader Intelligence Guide → Key
+ * Takeaways → deep sections). The Executive Brief section ends where the
+ * next H2 begins; we splice at that boundary. When the brief is absent
+ * (sparse runs) we fall back to prepending so the guide still appears
+ * at the top of the body.
+ *
+ * Implementation uses `indexOf` rather than a regex so the splice point
+ * is deterministic and immune to polynomial-regex backtracking on
+ * pathological input.
+ *
+ * @param bodyHtml - Rendered article body
+ * @param guideHtml - Reader Intelligence Guide HTML fragment
+ * @returns Body HTML with the guide spliced after the Executive Brief
+ */
+export declare function insertReaderGuideAfterExecutiveBrief(bodyHtml: string, guideHtml: string): string;
 /**
  * Run the full aggregate → render → write pipeline for one run.
  *

package/scripts/aggregator/article-generator.js

@@ -10,9 +10,14 @@
  *
  * Usage:
  *   npm run generate-article -- --run analysis/daily/2026-01-15/breaking-run1
- *   npm run generate-article -- --run ... --lang en --lang sv
  *   npm run generate-article -- --run ... --out-dir news --title "Headline"
  *
+ * **Always-14-languages-always-HTML contract**: every CLI invocation
+ * renders every supported language to HTML. The legacy `--lang` /
+ * `--language` / `--markdown-only` flags have been removed. The
+ * programmatic `generateArticle()` API still accepts `langs` and
+ * `markdownOnly` for tests that need to scope a render for speed.
+ *
  * Designed to be idempotent: running again with no changes overwrites
  * identical files byte-for-byte.
  */
@@ -24,7 +29,7 @@ import { resolveRunId as _resolveRunId } from './manifest/index.js';
 import { resolveArticleMetadata, extractStrongProseLine, } from './article-metadata.js';
 import { buildArticleMeta, serializeArticleMeta } from './article-meta.js';
 import { renderMarkdown } from './markdown-renderer.js';
-import { wrapArticleHtml, getArticleFilename } from './article-html.js';
+import { wrapArticleHtml, getArticleFilename, localizeArticleBody } from './article-html.js';
 import { buildReaderIntelligenceGuideHtml, stripInlineReaderGuide, } from './reader-intelligence-guide.js';
 import { ALL_LANGUAGES } from '../constants/language-core.js';
 import { blobUrl } from './infra/github-urls.js';
@@ -48,9 +53,6 @@ function applyFlagResult(acc, result) {
         case 'since':
             acc.since = result.value;
             return;
-        case 'lang':
-            acc.langs.push(result.value);
-            return;
         case 'outDir':
             acc.outDir = result.value;
             return;
@@ -60,9 +62,6 @@ function applyFlagResult(acc, result) {
         case 'description':
             acc.description = result.value;
             return;
-        case 'markdownOnly':
-            acc.markdownOnly = true;
-            return;
         default: {
             // Exhaustiveness guard — if a new FlagResult kind is added without a
             // matching case the compiler will surface the gap.
@@ -75,9 +74,7 @@ export function parseCliArgs(argv, repoRoot) {
     const acc = {
         runDir: null,
         all: false,
-        langs: [],
         outDir: path.join(repoRoot, 'news'),
-        markdownOnly: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i] ?? '';
@@ -105,10 +102,14 @@ export function parseCliArgs(argv, repoRoot) {
     const opts = {
         runDir: acc.runDir,
         all: acc.all,
-        langs: acc.langs.length > 0 ? acc.langs : [...ALL_LANGUAGES],
+        // Always render every language — the `--lang/--language` flags have
+        // been removed in the always-14-languages contract.
+        langs: [...ALL_LANGUAGES],
         outDir: acc.outDir,
         repoRoot,
-        markdownOnly: acc.markdownOnly,
+        // Always emit HTML — the `--markdown-only` flag has been removed in
+        // the always-HTML contract.
+        markdownOnly: false,
         ...(acc.since !== undefined ? { since: acc.since } : {}),
         ...(acc.title !== undefined ? { title: acc.title } : {}),
         ...(acc.description !== undefined ? { description: acc.description } : {}),
@@ -117,7 +118,7 @@ export function parseCliArgs(argv, repoRoot) {
 }
 /**
  * Resolve one CLI flag to a {@link FlagResult}. Throws `Error` for any
- * unsupported flag or language code.
+ * unsupported flag.
  *
  * @param flag - Flag name (e.g. `--run`)
  * @param takeValue - Lazily returns the value argument for value-bearing flags
@@ -137,14 +138,6 @@ function applyCliFlag(flag, takeValue) {
             }
             return { kind: 'since', value };
         }
-        case '--lang':
-        case '--language': {
-            const value = takeValue();
-            if (!ALL_LANGUAGES.includes(value)) {
-                throw new Error(`Unsupported language code: ${value}`);
-            }
-            return { kind: 'lang', value: value };
-        }
         case '--out-dir':
         case '--output':
             return { kind: 'outDir', value: path.resolve(takeValue()) };
@@ -152,13 +145,19 @@ function applyCliFlag(flag, takeValue) {
             return { kind: 'title', value: takeValue() };
         case '--description':
             return { kind: 'description', value: takeValue() };
-        case '--markdown-only':
-            return { kind: 'markdownOnly' };
         case '--help':
         case '-h':
             printHelp();
             process.exit(0);
         // eslint-disable-next-line no-fallthrough
+        case '--lang':
+        case '--language':
+        case '--markdown-only':
+            // Removed in the always-14-languages-always-HTML contract — every
+            // article.md now always renders to all 14 supported languages and
+            // HTML emission cannot be skipped from the CLI.
+            throw new Error(`Flag ${flag} has been removed. The CLI always renders all 14 languages with HTML output. ` +
+                `See Article-Generation.md § "CLI contract" for the new always-on contract.`);
         default:
             throw new Error(`Unknown argument: ${flag}`);
     }
@@ -183,19 +182,22 @@ function printHelp() {
         '  generate-article --all [--since YYYY-MM-DD] [options]',
         '',
         'Aggregate analysis artifacts from an `analysis/daily/**/<run>` directory',
-        'into a canonical Markdown document and render it to HTML in all 14',
-        'languages. The `--all` form walks every run under `analysis/daily/`',
-        'and regenerates the full historic catalogue in one pass.',
+        'into a canonical Markdown document and render it to HTML in **all 14',
+        'supported languages** (en, sv, da, no, fi, de, fr, es, nl, ar, he, ja,',
+        'ko, zh). The `--all` form walks every run under `analysis/daily/` and',
+        'regenerates the full historic catalogue in one pass.',
+        '',
+        'The 14-language HTML render is **always on** — there is no flag to',
+        'scope a render to a single language or to skip HTML emission. Every',
+        'article.md always produces 14 corresponding `<slug>-<lang>.html` files.',
         '',
         'Options:',
         '  --run <path>          Analysis run directory (single-run mode)',
         '  --all                 Batch-regenerate every run under analysis/daily/',
         '  --since YYYY-MM-DD    With --all: skip runs dated before this cut-off',
-        '  --lang <code>         Language to render (repeatable; default: all 14)',
         '  --out-dir <path>      Output directory (default: news/)',
         '  --title <text>        Override article title (single-run only)',
         '  --description <text>  Override article meta description (single-run only)',
-        '  --markdown-only       Write only the source .md (skip HTML)',
         '  --help, -h            Show this help',
         '',
     ].join('\n'));
@@ -347,13 +349,21 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
     bodyHtml = bodyHtml.replace(/<h1[^>]*>[\s\S]*?<\/h1>\s*/, '');
     const guideHtml = buildReaderIntelligenceGuideHtml(lang, aggregated.sectionToc, aggregated.includedArtifacts);
     if (guideHtml) {
-        // Prepend the guide to the body so it always appears at the top of
-        // the rendered content, immediately after the chrome header. The
-        // article chrome in wrapArticleHtml wraps the body in an <article>
-        // with its own <header>/<h1>, so prepending here is deterministic
-        // and avoids fragile in-body heading searches.
-        bodyHtml = guideHtml + '\n' + bodyHtml;
+        // Insert the guide IMMEDIATELY AFTER the Executive Brief section so
+        // the rendered HTML body order matches the documented article
+        // skeleton (Article-Generation.md §"Article skeleton"):
+        //   1. Executive Brief
+        //   2. Reader Intelligence Guide
+        //   3. Key Takeaways
+        //   4. … deep sections
+        // We splice at the start of the next H2 after the Executive Brief
+        // anchor; when the brief is missing (sparse runs) we fall back to
+        // prepending so the guide still appears at the top of the body.
+        bodyHtml = insertReaderGuideAfterExecutiveBrief(bodyHtml, guideHtml);
     }
+    // Localize Tradecraft References, Analysis Index, and other appendix
+    // section headings and content into the target language.
+    bodyHtml = localizeArticleBody(bodyHtml, lang);
     // When a per-language translated source exists, prefer a summary derived
     // from it so the `<meta description>` matches the visible prose. The
     // editorial title still comes from the English resolver (per-language
@@ -380,6 +390,60 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
     fs.writeFileSync(path.join(opts.outDir, filename), html, 'utf8');
     return filename;
 }
+/**
+ * Insert the regenerated Reader Intelligence Guide HTML immediately after
+ * the Executive Brief section so the rendered article body matches the
+ * documented order (Executive Brief → Reader Intelligence Guide → Key
+ * Takeaways → deep sections). The Executive Brief section ends where the
+ * next H2 begins; we splice at that boundary. When the brief is absent
+ * (sparse runs) we fall back to prepending so the guide still appears
+ * at the top of the body.
+ *
+ * Implementation uses `indexOf` rather than a regex so the splice point
+ * is deterministic and immune to polynomial-regex backtracking on
+ * pathological input.
+ *
+ * @param bodyHtml - Rendered article body
+ * @param guideHtml - Reader Intelligence Guide HTML fragment
+ * @returns Body HTML with the guide spliced after the Executive Brief
+ */
+export function insertReaderGuideAfterExecutiveBrief(bodyHtml, guideHtml) {
+    const execBriefAnchor = 'id="section-executive-brief"';
+    const briefIdx = bodyHtml.indexOf(execBriefAnchor);
+    if (briefIdx === -1) {
+        return guideHtml + '\n' + bodyHtml;
+    }
+    // Skip the Executive Brief opening tag itself, then walk forward to the
+    // next H2 — that's where the next section starts and where we want to
+    // splice the guide. `<h2 ` matches a tag with attributes; `<h2>` matches
+    // a bare tag (defensive).
+    const afterBrief = briefIdx + execBriefAnchor.length;
+    const nextH2Tagged = bodyHtml.indexOf('<h2 ', afterBrief);
+    const nextH2Bare = bodyHtml.indexOf('<h2>', afterBrief);
+    const nextH2 = pickEarliestIndex(nextH2Tagged, nextH2Bare);
+    if (nextH2 === -1) {
+        // Executive Brief is the only section — append the guide at the end.
+        return bodyHtml + '\n' + guideHtml;
+    }
+    return bodyHtml.slice(0, nextH2) + guideHtml + '\n' + bodyHtml.slice(nextH2);
+}
+/**
+ * Return the smaller of two `indexOf` results, treating `-1` as "not
+ * found" so the caller gets `-1` only when both probes failed. Extracted
+ * to keep {@link insertReaderGuideAfterExecutiveBrief} under the
+ * useless-assignment lint.
+ *
+ * @param a - First `indexOf` result
+ * @param b - Second `indexOf` result
+ * @returns Smaller non-negative index, or `-1` when both are `-1`
+ */
+function pickEarliestIndex(a, b) {
+    if (a === -1)
+        return b;
+    if (b === -1)
+        return a;
+    return Math.min(a, b);
+}
 /**
  * Safely look up one language entry in a {@link ResolvedMetadata} map.
  * The runtime shape is always complete (one entry per language), but the

package/scripts/aggregator/article-html.d.ts

@@ -84,6 +84,16 @@ export declare function buildArticleHreflangLinks(articleSlug: string): string;
  * @returns HTML fragment for the sidebar, or `""` when no TOC is needed
  */
 export declare function buildArticleToc(entries: readonly ArticleTocEntry[], lang: LanguageCode): string;
+/**
+ * Localize the Tradecraft References and Analysis Index sections in the
+ * rendered article body HTML. Replaces English headings, introductions,
+ * sub-headings, and table headers with translated equivalents.
+ *
+ * @param bodyHtml - The rendered HTML body (from Markdown)
+ * @param lang - Target language code
+ * @returns HTML body with localized appendix sections
+ */
+export declare function localizeArticleBody(bodyHtml: string, lang: LanguageCode): string;
 /**
  * Render the full article HTML document with the shared chrome.
  *