euparliamentmonitor 0.9.25 → 0.9.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.9.25",
+  "version": "0.9.27",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",

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

@@ -2,6 +2,7 @@ export { parseCliArgs, type CliOptions } from './generator/cli.js';
 export { buildArticleSlug, sanitizeRunSuffix, extractDefaultDescription, } from './generator/slug.js';
 export { discoverAnalysisRuns, groupRunsForCollision, type DiscoveredRun, } from './generator/discovery.js';
 export { insertReaderGuideAfterExecutiveBrief } from './generator/reader-guide-insertion.js';
+export { estimateReadingMinutes, buildLayerReadingTimes, splitBodyIntoDisclosureLayers, } from './progressive-disclosure.js';
 export { generateArticle, type GenerateResult } from './generator/render-one.js';
 export { generateAllArticles } from './generator/render-batch.js';
 /**

package/scripts/aggregator/article-generator.js

@@ -38,6 +38,8 @@ export { buildArticleSlug, sanitizeRunSuffix, extractDefaultDescription, } from
 export { discoverAnalysisRuns, groupRunsForCollision, } from './generator/discovery.js';
 // Reader guide insertion
 export { insertReaderGuideAfterExecutiveBrief } from './generator/reader-guide-insertion.js';
+// Progressive disclosure reading-time helpers
+export { estimateReadingMinutes, buildLayerReadingTimes, splitBodyIntoDisclosureLayers, } from './progressive-disclosure.js';
 // Single-run + batch orchestrators
 export { generateArticle } from './generator/render-one.js';
 export { generateAllArticles } from './generator/render-batch.js';

package/scripts/aggregator/generator/render-one.js

@@ -27,6 +27,7 @@ import { blobUrl } from '../infra/github-urls.js';
 import { buildArticleSlug } from './slug.js';
 import { discoverAnalysisRuns } from './discovery.js';
 import { insertReaderGuideAfterExecutiveBrief } from './reader-guide-insertion.js';
+import { buildLayerReadingTimes, splitBodyIntoDisclosureLayers, } from '../progressive-disclosure.js';
 /**
  * Escape a string for a conservative double-quoted YAML scalar.
  *
@@ -138,6 +139,7 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
     bodyHtml = localizeArticleBody(bodyHtml, lang);
     bodyHtml = enhanceTradecraftCards(bodyHtml, lang);
     bodyHtml = enhanceAnalysisIndexCards(bodyHtml, lang);
+    const readingTimes = buildLayerReadingTimes(splitBodyIntoDisclosureLayers(bodyHtml).wordCounts);
     const entry = getMetadataEntry(chromeOptions.metadata, lang);
     const perLangDescription = lang !== 'en' && metaSource !== aggregated.markdown
         ? extractStrongProseLine(metaSource) || entry.description
@@ -157,6 +159,7 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
         articleCount: chromeOptions.articleCount,
         isBasedOn: aggregated.includedArtifacts.map((a) => blobUrl(a.repoRelPath)),
         mentions: chromeOptions.mentions,
+        readingTimes,
     });
     const filename = getArticleFilename(slug, lang);
     fs.writeFileSync(path.join(opts.outDir, filename), html, 'utf8');

package/scripts/aggregator/html/shell.d.ts

@@ -1,5 +1,6 @@
 import type { LanguageCode } from '../../types/index.js';
 import { type ArticleTocEntry } from './toc.js';
+import { type LayerReadingTimes } from '../progressive-disclosure.js';
 export type { ArticleTocEntry } from './toc.js';
 /** Publisher organization name used in JSON-LD, meta tags. */
 export declare const PUBLISHER_NAME = "Hack23 AB";
@@ -16,6 +17,11 @@ export interface WrapArticleOptions {
     readonly articleSlug: string;
     /** Pre-rendered HTML body fragment (from `renderMarkdown`). */
     readonly body: string;
+    /**
+     * Enable reader-friendly post-processing for rendered HTML body text.
+     * Defaults to `true` for public HTML output.
+     */
+    readonly readerFriendly?: boolean;
     /** Article title — shown in `<title>`, breadcrumb, OG/Twitter meta. */
     readonly title: string;
     /** Article description — shown in `<meta name="description">` and OG. */
@@ -69,6 +75,8 @@ export interface WrapArticleOptions {
      * are language-independent proper nouns.
      */
     readonly mentions?: readonly string[];
+    /** Optional precomputed reading-time estimates per disclosure layer. */
+    readonly readingTimes?: LayerReadingTimes;
 }
 /**
  * Render the full article HTML document with the shared chrome.

package/scripts/aggregator/html/shell.js

@@ -16,7 +16,6 @@ import { ALL_LANGUAGES, PAGE_TITLES, SKIP_LINK_TEXTS, ARTICLE_NAV_LABELS, BACK_T
 import { buildOgLocaleTags } from '../../constants/og-locales.js';
 import { ORG_SAME_AS, buildTwitterAttributionTags } from '../../constants/social-handles.js';
 import { escapeHTML } from '../../utils/file-utils.js';
-import { stripHtmlTags } from '../../utils/html-sanitize.js';
 import { buildResponsiveIconLinks, buildResponsiveSocialImageMeta, buildSiteFooter, buildSiteHeader, buildPageBanner, } from '../../templates/section-builders.js';
 import { getPoliticalIntelligenceFilename } from '../../generators/political-intelligence.js';
 import { getSitemapFilename } from '../../generators/sitemap/index.js';
@@ -25,10 +24,85 @@ import { clampForBudget } from '../metadata/seo-budgets.js';
 import { getArticleFilename, buildArticleHreflangLinks, buildLanguageSwitcher, } from './hreflang.js';
 import { buildArticleToc } from './toc.js';
 import { blobUrl } from '../infra/github-urls.js';
+import { applyReaderFriendlyTransform } from '../reader-friendly-transform.js';
+import { buildLayerReadingTimes, buildProgressiveDisclosureBody, } from '../progressive-disclosure.js';
 /** Publisher organization name used in JSON-LD, meta tags. */
 export const PUBLISHER_NAME = 'Hack23 AB';
 /** Site name used across meta tags and structured data. */
 export const SITE_NAME = 'EU Parliament Monitor';
+/**
+ * Trailing separator characters (whitespace + editorial punctuation) that
+ * may dangle after a `Published …` tail has been removed.
+ */
+const TRAILING_SEPARATOR_CHARS = new Set(['\u2014', '\u2013', '|', ':', ';', ',', '-']);
+/**
+ * Linear-time trailing trim of whitespace and editorial separator
+ * punctuation. Avoids the polynomial backtracking that an unanchored
+ * `/[\s…]+$/` character-class quantifier exhibits on adversarial input.
+ *
+ * @param value - Text whose trailing separators should be removed
+ * @returns `value` without trailing whitespace/separator characters
+ */
+function trimTrailingSeparators(value) {
+    let end = value.length;
+    while (end > 0) {
+        const ch = value.charAt(end - 1);
+        if (TRAILING_SEPARATOR_CHARS.has(ch) || /\s/u.test(ch)) {
+            end -= 1;
+        }
+        else {
+            break;
+        }
+    }
+    return value.slice(0, end);
+}
+/**
+ * Anchored `Published YYYY-MM-DD` tail matcher. The leading `Published`
+ * literal keeps the match deterministic (no ambiguous leading-whitespace
+ * quantifier), so it is linear on uncontrolled input.
+ */
+const PUBLISHED_DATE_TAIL_RE = /Published\s+\d{4}-\d{2}-\d{2}\.?\s*$/iu;
+/**
+ * Remove leaked `Published YYYY-MM-DD` tails from social descriptions.
+ *
+ * @param value - Raw description candidate
+ * @returns Description with trailing publication-date boilerplate removed
+ */
+function stripPublishedDateTail(value) {
+    if (!value)
+        return '';
+    const withoutTail = value.replace(PUBLISHED_DATE_TAIL_RE, '');
+    return trimTrailingSeparators(withoutTail).trim();
+}
+/**
+ * Resolve a publish-date-safe description: prefer the stripped value, and
+ * only fall back to the original when no `Published …` tail was present.
+ * When the original was *only* a publish-date tail, stripping yields an
+ * empty string and we must not re-introduce the leaked tail.
+ *
+ * @param value - Raw description candidate
+ * @returns Stripped description, or empty when the original was tail-only
+ */
+function safeDescriptionWithoutPublishedTail(value) {
+    const stripped = stripPublishedDateTail(value);
+    if (stripped)
+        return stripped;
+    return PUBLISHED_DATE_TAIL_RE.test(value) ? '' : value;
+}
+/**
+ * Strip numbered list prefixes from JSON-LD mention labels.
+ *
+ * @param name - Raw mention label
+ * @returns Mention label without leading numeric hierarchy markers
+ */
+function sanitizeMentionName(name) {
+    let cleaned = name.trim();
+    while (/^\d+\./u.test(cleaned)) {
+        cleaned = cleaned.replace(/^\d+\./u, '').trimStart();
+    }
+    cleaned = cleaned.replace(/^\d+\s+/u, '').replace(/^\.\s*/u, '');
+    return cleaned.trim();
+}
 /**
  * Compute the per-surface SEO-budget-clamped variants of the article
  * title and description for a single render. See
@@ -44,17 +118,19 @@ export const SITE_NAME = 'EU Parliament Monitor';
  * @returns One {@link SeoClampedSurfaces} record per article render
  */
 function computeSeoClamps(options, lang, siteTitle) {
+    const safeMetaDescription = safeDescriptionWithoutPublishedTail(options.description);
     const pageTitle = buildPageTitle(options.title, lang, siteTitle);
     const ogTitleClamped = clampForBudget(options.title, lang, 'ogTitle');
     const twitterTitleClamped = clampForBudget(options.title, lang, 'twitterTitle');
-    const metaDescriptionClamped = clampForBudget(options.description, lang, 'metaDescription');
+    const metaDescriptionClamped = clampForBudget(safeMetaDescription, lang, 'metaDescription');
     // og:description and twitter:description prefer the longer BLUF
     // paragraph (extendedDescription) so social-card previews show the
     // full lede; fall back to the short meta description when the
     // extended one is empty.
-    const socialSource = options.extendedDescription && options.extendedDescription.length > 0
+    const socialSourceRaw = options.extendedDescription && options.extendedDescription.length > 0
         ? options.extendedDescription
-        : options.description;
+        : safeMetaDescription;
+    const socialSource = stripPublishedDateTail(socialSourceRaw) || safeMetaDescription;
     const ogDescriptionClamped = clampForBudget(socialSource, lang, 'ogDescription');
     const twitterDescriptionClamped = clampForBudget(socialSource, lang, 'twitterDescription');
     const imageAltClamped = clampForBudget(`${options.title}${getTitleSeparator(lang)}${siteTitle}`, lang, 'imageAlt');
@@ -110,13 +186,20 @@ export function wrapArticleHtml(options) {
     const tocHtml = buildArticleToc(options.toc ?? [], safeLang);
     const articleMainClass = tocHtml.length > 0 ? 'article-main--with-toc' : 'article-main--no-toc';
     const articleSectionLabel = getLocalizedArticleTypePlain(options.articleType, safeLang);
+    const disclosureBody = buildProgressiveDisclosureBody(options.body);
+    const transformedBodyHtml = options.readerFriendly === false
+        ? disclosureBody.bodyHtml
+        : applyReaderFriendlyTransform(disclosureBody.bodyHtml);
     // Count words from the rendered body for the JSON-LD `wordCount`
     // field (Google's NewsArticle structured-data validator emits a
     // warning when this is missing). Done by stripping HTML tags from
     // the rendered body then splitting on whitespace — fast and
     // CodeQL-safe.
-    const bodyText = stripHtmlTags(options.body);
-    const wordCount = bodyText.split(/\s+/u).filter((w) => w.length > 0).length;
+    const wordCount = disclosureBody.wordCounts.quick +
+        disclosureBody.wordCounts.analysis +
+        disclosureBody.wordCounts.intelligence;
+    const readingTimes = options.readingTimes ?? buildLayerReadingTimes(disclosureBody.wordCounts);
+    const readingTimeLine = `⏱️ Quick read: ${readingTimes.quickRead} min · Full analysis: ${readingTimes.fullAnalysis} min · Complete intelligence: ${readingTimes.completeIntelligence} min`;
     // Pre-compute the per-surface SEO-budget-clamped variants of title
     // and description. Each surface gets its own clamp tuned to the
     // documented platform envelope (Google/Bing SERP, Facebook/LinkedIn
@@ -152,6 +235,9 @@ export function wrapArticleHtml(options) {
             height: 630,
         },
     ];
+    const sanitizedMentions = (options.mentions ?? [])
+        .map((name) => sanitizeMentionName(name))
+        .filter(Boolean);
     const jsonLd = {
         '@context': 'https://schema.org',
         '@type': 'NewsArticle',
@@ -194,9 +280,9 @@ export function wrapArticleHtml(options) {
                 isBasedOn: options.isBasedOn.map((url) => ({ '@type': 'CreativeWork', url })),
             }
             : {}),
-        ...(options.mentions && options.mentions.length > 0
+        ...(sanitizedMentions.length > 0
             ? {
-                mentions: options.mentions.map((name) => ({
+                mentions: sanitizedMentions.map((name) => ({
                     '@type': 'Organization',
                     name,
                 })),
@@ -306,10 +392,11 @@ ${tocHtml}    <article class="article-body" lang="${safeLang}">
         <p class="article-kicker">${escapeHTML(getLocalizedArticleType(options.articleType, safeLang))}</p>
         <h1>${escapeHTML(options.title)}</h1>
         <p class="article-dek">${escapeHTML(options.description)}</p>
+        <p class="article-reading-times" aria-label="Estimated reading time">${escapeHTML(readingTimeLine)}</p>
         <p class="article-meta"><time datetime="${options.date}">${options.date}</time> · EU Parliament Monitor</p>
       </header>
       ${sourceMdLink}
-      ${options.body}
+      ${transformedBodyHtml}
     </article>
   </main>
 

package/scripts/aggregator/html/toc.js

@@ -14,6 +14,7 @@ import { READER_GUIDE_SECTION_ID } from '../reader-guide-constants.js';
 import { READER_GUIDE_TITLE_LABELS, getReaderGuideSectionIcon, } from '../reader-intelligence-guide.js';
 import { TRADECRAFT_SECTION_ID, MANIFEST_SECTION_ID, SUPPLEMENTARY_SECTION_ID, } from '../artifact-order.js';
 import { KEY_TAKEAWAYS_SECTION_ID } from '../key-takeaways.js';
+import { resolveDisclosureLayer } from '../progressive-disclosure.js';
 /**
  * Resolve a localized title for a TOC entry based on its section ID.
  * Falls back to the original English title if no translation is available.
@@ -94,7 +95,9 @@ export function buildArticleToc(entries, lang) {
         .map((e) => {
         const displayTitle = getLocalizedTocTitle(e.id, e.title, lang);
         const icon = getTocSectionIcon(e.id);
-        return `        <li><a href="#${escapeHTML(e.id)}"><span class="article-toc-icon" aria-hidden="true">${icon}</span> <span class="article-toc-text">${escapeHTML(displayTitle)}</span></a></li>`;
+        const layer = resolveDisclosureLayer(e.id);
+        const layerBadge = layer === 'quick' ? 'L1' : layer === 'analysis' ? 'L2' : 'L3';
+        return `        <li data-layer="${layer}"><a href="#${escapeHTML(e.id)}"><span class="article-toc-icon" aria-hidden="true">${icon}</span> <span class="article-toc-text">${escapeHTML(displayTitle)}</span><span class="article-toc-layer article-toc-layer--${layer}" aria-label="Layer ${layerBadge}">${layerBadge}</span></a></li>`;
     })
         .join('\n');
     return [

package/scripts/aggregator/metadata/fallback-synth.d.ts

@@ -0,0 +1,39 @@
+import type { PerLanguageInputs } from './per-language-resolver.js';
+/**
+ * Humanize an article-type slug for fallback metadata synthesis.
+ *
+ * @param articleType - Canonical article-type slug
+ * @returns Title-cased label with spaces instead of hyphens
+ */
+export declare function humanizeArticleTypeLabel(articleType: string): string;
+/**
+ * Format `YYYY-MM-DD` into `Mon YYYY`; falls back to the raw date when invalid.
+ *
+ * Formats with the target language (falling back to `en`) so the synthesized
+ * fallback title stays locale-appropriate for Latin non-EN locales (e.g.
+ * `sv`/`fr`) instead of emitting an English month label on every page.
+ *
+ * @param date - ISO article date
+ * @param lang - Target language code driving the month-label locale
+ * @returns Month/year label suitable for fallback titles
+ */
+export declare function formatMonthYear(date: string, lang: string): string;
+/**
+ * Hard fallback title synthesizer when all resolved candidates are contaminated.
+ * Shape: `EP <Article Type>: <Top Finding> — <Mon YYYY>`.
+ *
+ * @param input - Per-language resolver inputs
+ * @param topFindingSource - Best available finding/summary source text
+ * @param contextualFallback - Last-resort contextual fallback title
+ * @returns Reader-facing synthesized fallback title
+ */
+export declare function synthesizeFallbackTitle(input: PerLanguageInputs, topFindingSource: string, contextualFallback: string): string;
+/**
+ * Hard fallback description synthesizer when the resolved description leaks
+ * pipeline jargon.
+ *
+ * @param input - Per-language resolver inputs
+ * @returns Reader-facing synthesized fallback description
+ */
+export declare function synthesizeFallbackDescription(input: PerLanguageInputs): string;
+//# sourceMappingURL=fallback-synth.d.ts.map

package/scripts/aggregator/metadata/fallback-synth.js

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @file Hard fallback metadata synthesizers for the per-language SEO
+ * resolver. These run only when every resolved title/description candidate is
+ * contaminated with pipeline jargon, producing reader-facing, search-safe copy
+ * from article context instead of leaking internal pipeline artifacts.
+ */
+import { budgetFor, classifyScript, clampForBudget } from './seo-budgets.js';
+import { composeContextualDescription, deriveHeadlineFromSummary, ensureDescriptionTerminator, hasLeakySeoToken, padDescriptionToFloor, sanitizeDescriptionCandidate, sanitizeTitleCandidate, } from './resolve-helpers.js';
+import { truncateTitle } from './text-utils.js';
+/**
+ * Humanize an article-type slug for fallback metadata synthesis.
+ *
+ * @param articleType - Canonical article-type slug
+ * @returns Title-cased label with spaces instead of hyphens
+ */
+export function humanizeArticleTypeLabel(articleType) {
+    return articleType
+        .split('-')
+        .filter(Boolean)
+        .map((token) => token.charAt(0).toUpperCase() + token.slice(1))
+        .join(' ');
+}
+/**
+ * Format `YYYY-MM-DD` into `Mon YYYY`; falls back to the raw date when invalid.
+ *
+ * Formats with the target language (falling back to `en`) so the synthesized
+ * fallback title stays locale-appropriate for Latin non-EN locales (e.g.
+ * `sv`/`fr`) instead of emitting an English month label on every page.
+ *
+ * @param date - ISO article date
+ * @param lang - Target language code driving the month-label locale
+ * @returns Month/year label suitable for fallback titles
+ */
+export function formatMonthYear(date, lang) {
+    const parsed = new Date(`${date}T00:00:00Z`);
+    if (Number.isNaN(parsed.getTime()))
+        return date;
+    return new Intl.DateTimeFormat([lang, 'en'], {
+        month: 'short',
+        year: 'numeric',
+        timeZone: 'UTC',
+    }).format(parsed);
+}
+/**
+ * Hard fallback title synthesizer when all resolved candidates are contaminated.
+ * Shape: `EP <Article Type>: <Top Finding> — <Mon YYYY>`.
+ *
+ * @param input - Per-language resolver inputs
+ * @param topFindingSource - Best available finding/summary source text
+ * @param contextualFallback - Last-resort contextual fallback title
+ * @returns Reader-facing synthesized fallback title
+ */
+export function synthesizeFallbackTitle(input, topFindingSource, contextualFallback) {
+    // The synthesized shape (`EP <Article Type>: <Top Finding> — <Mon YYYY>`)
+    // is Latin/English by construction (the `EP <Article Type>` lead-in and
+    // colon punctuation). Emitting it on a non-Latin locale would ship a
+    // pure-ASCII `<title>`, violating the locale-glyph contract (Gate 4a). For
+    // those locales we defer to the localized contextual fallback instead.
+    if (classifyScript(input.lang) !== 'latin')
+        return contextualFallback;
+    const topFinding = sanitizeTitleCandidate(deriveHeadlineFromSummary(topFindingSource));
+    const articleTypeLabel = humanizeArticleTypeLabel(input.articleType);
+    const monthYear = formatMonthYear(input.date, input.lang);
+    const synthesized = topFinding
+        ? `EP ${articleTypeLabel}: ${topFinding} — ${monthYear}`
+        : `EP ${articleTypeLabel} — ${input.date}`;
+    const candidate = truncateTitle(synthesized) || synthesized;
+    return !candidate || hasLeakySeoToken(candidate) ? contextualFallback : candidate;
+}
+/**
+ * Hard fallback description synthesizer when the resolved description leaks
+ * pipeline jargon.
+ *
+ * @param input - Per-language resolver inputs
+ * @returns Reader-facing synthesized fallback description
+ */
+export function synthesizeFallbackDescription(input) {
+    const templateSubtitle = sanitizeDescriptionCandidate(input.template.subtitle);
+    const articleTypeLabel = humanizeArticleTypeLabel(input.articleType);
+    const base = templateSubtitle && !hasLeakySeoToken(templateSubtitle)
+        ? templateSubtitle
+        : `EP ${articleTypeLabel} update for ${input.date}.`;
+    const synthesized = composeContextualDescription(input.lang, base, { headline: '', summary: '' }, input.date, '');
+    const clamped = clampForBudget(synthesized, input.lang, 'metaDescription');
+    return padDescriptionToFloor(ensureDescriptionTerminator(input.lang, clamped, budgetFor(input.lang, 'metaDescription')), input.lang);
+}
+//# sourceMappingURL=fallback-synth.js.map

package/scripts/aggregator/metadata/per-language-resolver.d.ts

@@ -39,6 +39,7 @@
  */
 import type { LangTitleSubtitle, LanguageCode } from '../../types/index.js';
 import type { MetadataManifest, ResolvedMetadataEntry } from './types.js';
+export { appendRunNumberSuffix } from './resolve-script-utils.js';
 /**
  * Inputs to {@link resolveOneLanguage}. Extracting this struct keeps the
  * resolver's per-language loop body free of long argument lists.
@@ -63,18 +64,6 @@ export interface PerLanguageInputs {
         extendedSummary: string;
     } | null;
 }
-/**
- * No-op: run numbers must never appear in user-facing article titles.
- * Titles should always be readable article headlines without workflow
- * identifiers. This function is preserved for callsite backward
- * compatibility.
- *
- * @param seoTitle - SEO title (returned unchanged)
- * @param _lang - Language code (ignored)
- * @param _runId - Manifest run identifier (ignored)
- * @returns The unchanged input title
- */
-export declare function appendRunNumberSuffix(seoTitle: string, _lang: LanguageCode, _runId: string): string;
 /**
  * Build the editorial source object for one language. Prefers a translated
  * `executive-brief_<lang>.md` sibling, falls through to the English brief