euparliamentmonitor 0.9.1 → 0.9.3

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.1",
+  "version": "0.9.3",
   "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",
@@ -163,9 +163,9 @@
     "happy-dom": "20.9.0",
     "htmlhint": "1.9.2",
     "husky": "9.1.7",
-    "jscpd": "4.0.9",
+    "jscpd": "4.1.0",
     "knip": "^6.7.0",
-    "lint-staged": "17.0.2",
+    "lint-staged": "17.0.4",
     "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.d.ts

@@ -115,6 +115,17 @@ export declare function renderProvenanceBlock(params: {
  * @returns Markdown block with two subsections (methodologies, templates)
  */
 export declare function renderTradecraftAppendix(files: readonly string[]): string;
+/**
+ * Public re-export of the internal `humanize` helper so other aggregator
+ * modules (in particular `article-html.ts`) can derive the same display
+ * title from a file stem when no curated title is available. Keeping the
+ * single canonical implementation here avoids duplicate humanisation
+ * rules drifting across modules.
+ *
+ * @param stem - File stem (e.g. `electoral-cycle-methodology`)
+ * @returns Humanised title (e.g. `Electoral Cycle Methodology`)
+ */
+export declare function humanizeStem(stem: string): string;
 /**
  * Render the analysis-index appendix — a compact table of every included
  * artifact and its section, plus a direct link to the manifest.

package/scripts/aggregator/analysis-aggregator.js

@@ -213,19 +213,25 @@ export function renderTradecraftAppendix(files) {
         'This article is produced under the [Hack23 AB](https://hack23.com) intelligence tradecraft library. Every methodology and artifact template applied to this run is linked below.',
         '',
     ];
-    if (methods.length > 0) {
-        block.push('### Methodologies');
+    // Order: Artifact templates first (concrete deliverables readers
+    // recognise from the article body), then Methodologies (the underlying
+    // tradecraft library). This matches the natural reader flow — the
+    // article is built from artifacts, and the methodologies explain how
+    // each artifact is produced — and pairs with the contextual, kind-
+    // aware "View …" CTAs rendered in `enhanceTradecraftCards`.
+    if (templates.length > 0) {
+        block.push('### Artifact templates');
         block.push('');
-        for (const rel of methods) {
+        for (const rel of templates) {
             const stem = rel.split('/').pop()?.replace(/\.md$/i, '') ?? rel;
             block.push(`- [${humanize(stem)}](${githubBlobUrl(rel)})`);
         }
         block.push('');
     }
-    if (templates.length > 0) {
-        block.push('### Artifact templates');
+    if (methods.length > 0) {
+        block.push('### Methodologies');
         block.push('');
-        for (const rel of templates) {
+        for (const rel of methods) {
             const stem = rel.split('/').pop()?.replace(/\.md$/i, '') ?? rel;
             block.push(`- [${humanize(stem)}](${githubBlobUrl(rel)})`);
         }
@@ -233,6 +239,19 @@ export function renderTradecraftAppendix(files) {
     }
     return block.join('\n');
 }
+/**
+ * Public re-export of the internal `humanize` helper so other aggregator
+ * modules (in particular `article-html.ts`) can derive the same display
+ * title from a file stem when no curated title is available. Keeping the
+ * single canonical implementation here avoids duplicate humanisation
+ * rules drifting across modules.
+ *
+ * @param stem - File stem (e.g. `electoral-cycle-methodology`)
+ * @returns Humanised title (e.g. `Electoral Cycle Methodology`)
+ */
+export function humanizeStem(stem) {
+    return humanize(stem);
+}
 /**
  * Render the analysis-index appendix — a compact table of every included
  * artifact and its section, plus a direct link to the manifest.

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

@@ -100,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

@@ -29,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, localizeArticleBody } from './article-html.js';
+import { wrapArticleHtml, getArticleFilename, localizeArticleBody, enhanceTradecraftCards, enhanceAnalysisIndexCards, } 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';
@@ -349,16 +349,27 @@ 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);
+    // Replace the plain Tradecraft References bullet lists and the
+    // Analysis Index table with `pi-card-grid` cards. Runs for every
+    // language (including English) so the "much nicer" rendering matches
+    // the political-intelligence.html visual vocabulary site-wide.
+    bodyHtml = enhanceTradecraftCards(bodyHtml, lang);
+    bodyHtml = enhanceAnalysisIndexCards(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
@@ -385,6 +396,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

@@ -73,8 +73,10 @@ export declare function buildArticleHreflangLinks(articleSlug: string): string;
  * Build the article-level Table of Contents nav. Renders a labelled
  * `<nav class="article-toc">` with one `<a>` per H2 section, keyed by the
  * stable fragment ids produced by the aggregator. The containing `<aside>`
- * is styled as a sticky sidebar on wide viewports and collapses into a
- * `<details>` disclosure on narrow viewports via `styles.css`.
+ * is styled as a sticky, full-height sidebar on wide viewports and
+ * collapses into a `<details>` disclosure on narrow viewports via
+ * `styles.css`. Each entry is prefixed with a contextual emoji icon so
+ * readers can scan the navigation visually as well as textually.
  *
  * Returns an empty string when `entries` is empty so low-signal
  * `ANALYSIS_ONLY` articles (few sections, no value in a TOC) stay compact.
@@ -94,6 +96,46 @@ export declare function buildArticleToc(entries: readonly ArticleTocEntry[], lan
  * @returns HTML body with localized appendix sections
  */
 export declare function localizeArticleBody(bodyHtml: string, lang: LanguageCode): string;
+/**
+ * Replace the rendered Tradecraft References bullet lists with a
+ * `pi-card-grid` of richly described cards (icon, curated title,
+ * curated description, kind-aware CTA). The cards reuse the exact same
+ * class hooks as `political-intelligence.html`, so the site-wide CSS
+ * already styles them — no additional CSS is required.
+ *
+ * After the April-2026 reorder the rendered Markdown emits Artifact
+ * templates as the first sub-heading and Methodologies as the second,
+ * matching how readers encounter the run (artifacts first, methodology
+ * library second). The card upgrade follows the same order so the H3
+ * positions stay aligned with the kind-aware CTA labels.
+ *
+ * Falls back to the original Markdown-rendered list when the expected
+ * structure (H2 → intro paragraph → Artifact-templates sub-heading →
+ * `<ul>` → Methodologies sub-heading → `<ul>`) is missing, so partially
+ * stripped or unusual articles are not silently corrupted.
+ *
+ * @param bodyHtml - The (already-localised) article body HTML
+ * @param lang - Target language code for curated titles/descriptions
+ * @returns Body HTML with the tradecraft section upgraded to cards
+ */
+export declare function enhanceTradecraftCards(bodyHtml: string, lang: LanguageCode): string;
+/**
+ * Replace the Analysis Index `<table>` with a `pi-card-grid` of cards,
+ * one per included artifact. Each card renders the artifact's curated
+ * localised title + description, the section it contributed to, the
+ * run-relative path as inline `<code>`, and a "View on GitHub" CTA.
+ *
+ * Strategy: parse the rendered table's `<tbody>` rows (each row carries
+ * `[sectionId, <a href="…">stem</a>, runRelPath]`) and re-render the
+ * region between the table's opening wrapper and `</table>` as a card
+ * grid. The wrapping `<div class="table-scroll">` is dropped because
+ * the card grid handles its own responsive layout via flex/grid.
+ *
+ * @param bodyHtml - Article body HTML
+ * @param lang - Target language code
+ * @returns Body HTML with the Analysis Index upgraded to a card grid
+ */
+export declare function enhanceAnalysisIndexCards(bodyHtml: string, lang: LanguageCode): string;
 /**
  * Render the full article HTML document with the shared chrome.
  *