euparliamentmonitor 0.9.21 → 0.9.23

package/scripts/aggregator/metadata/seo-budgets.js

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
+// SPDX-License-Identifier: Apache-2.0
+import { HEADLINE_CLAUSE_BOUNDARIES } from './text-utils.js';
+/**
+ * Iteration helper — all three script families in a deterministic
+ * order (latin → cjk → rtl). Exported so test matrices and downstream
+ * tooling can walk every column of {@link SEO_BUDGETS} without
+ * duplicating the literal list.
+ */
+export const ALL_SCRIPT_FAMILIES = ['latin', 'cjk', 'rtl'];
+/**
+ * Classify a locale code into a script family. Used to look up the
+ * correct byte cap in {@link SEO_BUDGETS}.
+ *
+ * @param lang - BCP-47 language tag (one of the 14 publishing locales)
+ * @returns Script family for SEO budget lookup
+ */
+export function classifyScript(lang) {
+    if (lang === 'ar' || lang === 'he')
+        return 'rtl';
+    if (lang === 'ja' || lang === 'ko' || lang === 'zh')
+        return 'cjk';
+    return 'latin';
+}
+/**
+ * Per-surface × per-script byte cap table. Numbers reflect the
+ * narrower of Google / Bing / Facebook / Twitter documented envelopes,
+ * with a ~5 % safety margin so a snippet on the edge of the budget
+ * isn't truncated mid-glyph by the rendering platform.
+ *
+ * For `jsonLdHeadline` the Schema.org `NewsArticle.headline` cap is
+ * script-independent (Google validates the literal character count at
+ * 110) — same value across the row.
+ */
+export const SEO_BUDGETS = {
+    title: { latin: 60, cjk: 30, rtl: 55 },
+    metaDescription: { latin: 155, cjk: 78, rtl: 150 },
+    ogTitle: { latin: 95, cjk: 47, rtl: 90 },
+    ogDescription: { latin: 200, cjk: 100, rtl: 195 },
+    twitterTitle: { latin: 70, cjk: 35, rtl: 70 },
+    twitterDescription: { latin: 200, cjk: 100, rtl: 195 },
+    imageAlt: { latin: 125, cjk: 60, rtl: 120 },
+    jsonLdHeadline: { latin: 110, cjk: 110, rtl: 110 },
+};
+/**
+ * Resolve the byte cap for one `(lang, surface)` pair.
+ *
+ * @param lang - Publishing locale
+ * @param surface - SEO surface (see {@link SeoSurface})
+ * @returns Byte cap (positive integer)
+ */
+export function budgetFor(lang, surface) {
+    const family = classifyScript(lang);
+    return SEO_BUDGETS[surface][family];
+}
+// ────────────────────────────────────────────────────────────────────────
+// Script-aware truncator
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * CJK full-width clause boundaries — the breakpoints CJK readers
+ * expect a snippet to end at. Listed in preferred-break order: a
+ * sentence-final mark beats a comma which beats a middle-dot.
+ */
+const CJK_CLAUSE_BOUNDARIES = [
+    '。',
+    '！',
+    '？',
+    '、',
+    '；',
+    '：',
+    '——',
+    '—',
+    '・',
+];
+/**
+ * RTL sentence punctuation. Arabic uses U+061F (؟) for question mark
+ * and U+060C (،) for comma; full stop is the ASCII `.` (Hebrew uses
+ * `.` and `,` directly). Listed in preferred-break order.
+ */
+const RTL_CLAUSE_BOUNDARIES = ['. ', '؟ ', '! ', '، ', '؛ ', ' — ', ' – '];
+/**
+ * Soft-minimum fraction of the budget at which a clause-boundary break
+ * is acceptable. Below this fraction we fall through to whitespace
+ * truncation so we never ship a near-empty snippet just because the
+ * input started with a short clause.
+ */
+const SOFT_MIN_RATIO = 0.55;
+/**
+ * Trim trailing punctuation that would otherwise leave a snippet
+ * ending on a dangling separator or ellipsis. Mirrors the spirit of
+ * `text-utils.ts::TRAILING_PUNCT` but keeps full-width CJK marks
+ * intact when they sit at a natural sentence boundary.
+ *
+ * @param s - Input string to trim
+ * @returns Input with trailing separator-class characters removed
+ */
+function trimTrailingSeparators(s) {
+    return s.replace(/[\s,;:—\-–·•…]+$/u, '');
+}
+/**
+ * Pick the highest-priority clause boundary inside a candidate window.
+ * Iterates the boundary vocabulary in declared (preference) order and
+ * returns the first index that sits past the soft minimum.
+ *
+ * @param window - Candidate cut window (`text.slice(0, budget)`)
+ * @param boundaries - Boundary vocabulary, in preference order
+ * @param softMin - Soft-minimum cut position (chars)
+ * @returns Cut index, or -1 when no boundary qualifies
+ */
+function findClauseCut(window, boundaries, softMin) {
+    for (const boundary of boundaries) {
+        const idx = window.lastIndexOf(boundary);
+        if (idx >= softMin) {
+            return idx + boundary.length;
+        }
+    }
+    return -1;
+}
+/**
+ * Truncate `text` to fit `(lang, surface)` SEO byte budget. Prefers a
+ * natural clause boundary inside the script's punctuation vocabulary
+ * (CJK / RTL / Latin) before falling back to a whitespace break.
+ *
+ * Always returns `text` verbatim when it already fits (no ellipsis
+ * appended). When truncation happens an ellipsis (`…`) is appended for
+ * Latin / RTL; for CJK the full-width ellipsis (`…`) reads as a
+ * partial-thought marker and is also appended — Schema.org and Google
+ * accept either glyph in `headline` / `description`.
+ *
+ * @param text - Source text (already plain-text — no Markdown / HTML)
+ * @param lang - Publishing locale
+ * @param surface - Target SEO surface
+ * @returns Clamped text ≤ `budgetFor(lang, surface)` characters
+ */
+export function clampForBudget(text, lang, surface) {
+    const trimmed = text.trim();
+    const budget = budgetFor(lang, surface);
+    if (trimmed.length <= budget)
+        return trimmed;
+    const family = classifyScript(lang);
+    const softMin = Math.floor(budget * SOFT_MIN_RATIO);
+    // Reserve one char for the ellipsis we may append.
+    const window = trimmed.slice(0, budget - 1);
+    const boundaries = family === 'cjk'
+        ? CJK_CLAUSE_BOUNDARIES
+        : family === 'rtl'
+            ? RTL_CLAUSE_BOUNDARIES
+            : HEADLINE_CLAUSE_BOUNDARIES;
+    const clauseCut = findClauseCut(window, boundaries, softMin);
+    if (clauseCut > 0) {
+        const cleaned = trimTrailingSeparators(trimmed.slice(0, clauseCut));
+        if (cleaned.length >= softMin)
+            return cleaned;
+    }
+    // Whitespace-aware fallback. CJK text often has no ASCII spaces, so
+    // skip this step for CJK and fall straight through to the hard cut.
+    if (family !== 'cjk') {
+        const lastSpace = window.lastIndexOf(' ');
+        if (lastSpace >= softMin) {
+            const safe = trimTrailingSeparators(window.slice(0, lastSpace));
+            return `${safe}…`;
+        }
+    }
+    const hardCut = trimTrailingSeparators(window);
+    return `${hardCut}…`;
+}
+/**
+ * Compose `{title}{separator}{siteTitle}` while honouring the
+ * `(lang, surface)` budget. Drops the brand suffix entirely when the
+ * article title alone is already at or past the budget. Prefers the
+ * short site title when supplied and the full suffix doesn't fit.
+ *
+ * @param title - Article title (plain text)
+ * @param lang - Publishing locale
+ * @param surface - Target SEO surface (`title` / `ogTitle` / `twitterTitle`)
+ * @param opts - Optional brand suffix wiring
+ * @returns Composed title ≤ budget
+ */
+export function clampTitleForSurface(title, lang, surface, opts = {}) {
+    const budget = budgetFor(lang, surface);
+    const cleanTitle = title.trim();
+    const sep = opts.separator ?? '';
+    const full = opts.siteTitle ?? '';
+    const short = opts.shortSiteTitle ?? '';
+    // No brand suffix wiring — just clamp the title in isolation.
+    if (!full)
+        return clampForBudget(cleanTitle, lang, surface);
+    const fullSuffix = `${sep}${full}`;
+    const shortSuffix = short ? `${sep}${short}` : '';
+    // Best case: title + full suffix fits.
+    if (cleanTitle.length + fullSuffix.length <= budget) {
+        return `${cleanTitle}${fullSuffix}`;
+    }
+    // Second best: title + short suffix fits.
+    if (shortSuffix && cleanTitle.length + shortSuffix.length <= budget) {
+        return `${cleanTitle}${shortSuffix}`;
+    }
+    // Third: keep the title (clamped), drop the brand. Better SERP than
+    // a truncated headline followed by a clipped brand suffix.
+    return clampForBudget(cleanTitle, lang, surface);
+}
+//# sourceMappingURL=seo-budgets.js.map

package/scripts/aggregator/metadata/text-truncate.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Remove any trailing whitespace, stop-words (the/a/an/of/…) and
+ * trailing punctuation (including any pre-existing ellipsis). Implemented
+ * imperatively to avoid super-linear regex backtracking on the
+ * `(?:\s+stop-word)+$` pattern flagged by `security/detect-unsafe-regex`.
+ *
+ * @param input - Pre-clipped string to clean up
+ * @returns Cleaned string with no trailing stop-words or punctuation
+ */
+export declare function stripTrailingStopWordsAndPunctuation(input: string): string;
+/**
+ * Clamp a string to `DESCRIPTION_MAX_LENGTH` characters, appending
+ * an ellipsis when truncation actually happens. Does not break words if
+ * avoidable — a trailing partial word is trimmed back to the previous
+ * space first.
+ *
+ * @param text - Raw description text
+ * @returns Truncated description with trailing ellipsis when clipped
+ */
+export declare function truncateDescription(text: string): string;
+/**
+ * Clamp an extended description to {@link EXTENDED_DESCRIPTION_MAX_LENGTH}
+ * characters using the same sentence-boundary-preserving logic as
+ * {@link truncateDescription}. Returns `''` when the input is empty
+ * or shorter than the meta-description maximum (no point in emitting
+ * an "extended" description that's actually shorter than the regular
+ * one).
+ *
+ * @param text - Raw extended-description text (e.g. full BLUF paragraph)
+ * @returns Truncated extended description, or `''` when not worth emitting
+ */
+export declare function truncateExtendedDescription(text: string): string;
+/**
+ * Clamp a title to `TITLE_MAX_LENGTH` characters in the same
+ * word-boundary-preserving fashion as {@link truncateDescription}.
+ *
+ * **No mid-sentence ellipsis.** When the title overruns the budget and
+ * no natural clause boundary exists inside the
+ * `[HEADLINE_SOFT_MIN, TITLE_MAX_LENGTH]` window, this function returns
+ * an empty string instead of a mid-sentence `…` truncation. The empty
+ * return tells the caller to fall through to the next tier of the
+ * resolver ladder (template-fallback title with category + date),
+ * producing a complete, scan-friendly title rather than a clipped
+ * editorial fragment. Live-site regression (2026-05): titles such as
+ * `AI Trade Strategy: A Legislative First with Structural…` and
+ * `The European Parliament's 24 standing committees continued…`
+ * were emitted before this guard.
+ *
+ * @param text - Raw title text
+ * @returns Clause-truncated title (no ellipsis), or `''` when no
+ *   editorial clause boundary exists in the window
+ */
+export declare function truncateTitle(text: string): string;
+/**
+ * Return the first complete sentence from a prose paragraph, suitable
+ * for use as a fallback editorial title when the artefact H1 is
+ * categorical (e.g. `# EU Parliament Committee Reports`) and the
+ * resolver must derive `<title>` from the BLUF / lede summary instead.
+ *
+ * A "sentence" is the prefix up to the first sentence-terminator
+ * (`. `, `! `, `? `, `; `) inside the `[HEADLINE_SOFT_MIN,
+ * TITLE_MAX_LENGTH]` window. Common abbreviations (`Q1.`, `Q2.`,
+ * `H1.`, `H2.`, `Mr.`, `Mrs.`, `e.g.`, `i.e.`, `vs.`) are skipped
+ * so they don't terminate the sentence prematurely. When no
+ * acceptable terminator exists in the window, returns `''` so the
+ * resolver falls through to the next tier instead of feeding an
+ * over-budget paragraph into {@link truncateTitle} (which would also
+ * return `''`).
+ *
+ * @param paragraph - Prose paragraph (post-`stripInlineMarkdown`)
+ * @returns First sentence, or `''` when none can be identified within
+ *   the soft-min window
+ */
+export declare function extractFirstSentence(paragraph: string): string;
+//# sourceMappingURL=text-truncate.d.ts.map

package/scripts/aggregator/metadata/text-truncate.js

@@ -0,0 +1,277 @@
+// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @module Aggregator/Metadata/TextTruncate
+ * @description Byte-budget truncators and sentence-extraction helpers
+ * extracted from `text-utils.ts` to keep both modules under the 600-line
+ * drift-guard budget enforced by `test/unit/source-file-size.test.js`.
+ *
+ * This file is the **clamping layer** of the metadata text pipeline —
+ * after `shouldSkipDescriptionLine`/`stripInlineMarkdown` produce a
+ * candidate description / title, the helpers here apply the SEO-budget
+ * shape rules:
+ *
+ * - {@link truncateDescription} — clamp to `DESCRIPTION_MAX_LENGTH` on a
+ *   sentence/word boundary, appending `…` when truncation occurs.
+ * - {@link truncateExtendedDescription} — clamp to the longer
+ *   `EXTENDED_DESCRIPTION_MAX_LENGTH` (used by `og:description`).
+ * - {@link truncateTitle} — clamp to `TITLE_MAX_LENGTH` on a
+ *   **clause** boundary, returning `''` rather than emitting a
+ *   mid-sentence ellipsised title.
+ * - {@link extractFirstSentence} — return the first complete sentence
+ *   from a prose paragraph, or `''` when no clean terminator is
+ *   available within the soft-min window.
+ *
+ * Bounded-context rules match `text-utils.ts`:
+ * - **No upward imports** — pure helpers, no I/O, no globals.
+ * - **Deterministic** — same input always produces same output.
+ * - **Locale-agnostic** — operates on raw prose in any of the 14
+ *   publishing languages.
+ */
+import { ABBREVIATION_PREFIXES, DESCRIPTION_MAX_LENGTH, DESCRIPTION_MIN_LENGTH, EXTENDED_DESCRIPTION_MAX_LENGTH, EXTENDED_DESCRIPTION_MIN_LENGTH, HEADLINE_CLAUSE_BOUNDARIES, HEADLINE_HARD_MIN, HEADLINE_SOFT_MIN, TITLE_MAX_LENGTH, TRAILING_PUNCT, TRAILING_STOP_WORDS, } from './text-utils-constants.js';
+/**
+ * Remove any trailing whitespace, stop-words (the/a/an/of/…) and
+ * trailing punctuation (including any pre-existing ellipsis). Implemented
+ * imperatively to avoid super-linear regex backtracking on the
+ * `(?:\s+stop-word)+$` pattern flagged by `security/detect-unsafe-regex`.
+ *
+ * @param input - Pre-clipped string to clean up
+ * @returns Cleaned string with no trailing stop-words or punctuation
+ */
+export function stripTrailingStopWordsAndPunctuation(input) {
+    let result = input;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        while (result.length > 0 && TRAILING_PUNCT.test(result.charAt(result.length - 1))) {
+            result = result.slice(0, -1);
+            changed = true;
+        }
+        const lastSpace = result.lastIndexOf(' ');
+        if (lastSpace >= 0) {
+            const tail = result.slice(lastSpace + 1).toLowerCase();
+            if (TRAILING_STOP_WORDS.has(tail)) {
+                result = result.slice(0, lastSpace);
+                changed = true;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Clamp a string to `DESCRIPTION_MAX_LENGTH` characters, appending
+ * an ellipsis when truncation actually happens. Does not break words if
+ * avoidable — a trailing partial word is trimmed back to the previous
+ * space first.
+ *
+ * @param text - Raw description text
+ * @returns Truncated description with trailing ellipsis when clipped
+ */
+export function truncateDescription(text) {
+    if (text.length <= DESCRIPTION_MAX_LENGTH)
+        return text;
+    const cut = text.slice(0, DESCRIPTION_MAX_LENGTH);
+    // Prefer the last full sentence terminator within the cut so we don't
+    // end on a dangling determiner ("…year. The"). Period/!/? followed by
+    // a space marks a clean boundary. Only honour the boundary when it
+    // sits past the soft minimum so we keep enough body text to be useful.
+    const sentenceEnd = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('! '), cut.lastIndexOf('? '));
+    if (sentenceEnd >= DESCRIPTION_MIN_LENGTH) {
+        return cut.slice(0, sentenceEnd + 1).replace(/\s+$/, '');
+    }
+    const earlySentenceEnd = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('! '), cut.lastIndexOf('? '));
+    if (earlySentenceEnd >= Math.floor(DESCRIPTION_MIN_LENGTH / 3)) {
+        return cut.slice(0, earlySentenceEnd + 1).replace(/\s+$/, '');
+    }
+    const lastSpace = cut.lastIndexOf(' ');
+    let safe = lastSpace > DESCRIPTION_MAX_LENGTH - 60 ? cut.slice(0, lastSpace) : cut;
+    // Drop dangling stop-words and trailing punctuation/ellipsis so we
+    // never emit broken copy ("…year. The" → "…year.") or double-ellipsis
+    // ("The……") when the upstream input already carried an ellipsis.
+    safe = stripTrailingStopWordsAndPunctuation(safe);
+    return safe;
+}
+/**
+ * Clamp an extended description to {@link EXTENDED_DESCRIPTION_MAX_LENGTH}
+ * characters using the same sentence-boundary-preserving logic as
+ * {@link truncateDescription}. Returns `''` when the input is empty
+ * or shorter than the meta-description maximum (no point in emitting
+ * an "extended" description that's actually shorter than the regular
+ * one).
+ *
+ * @param text - Raw extended-description text (e.g. full BLUF paragraph)
+ * @returns Truncated extended description, or `''` when not worth emitting
+ */
+export function truncateExtendedDescription(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return '';
+    // Don't emit an extended description that is shorter than the
+    // short meta-description budget — there's no SEO win and it would
+    // make `og:description` shorter than `<meta description>`.
+    if (trimmed.length <= DESCRIPTION_MAX_LENGTH)
+        return '';
+    if (trimmed.length <= EXTENDED_DESCRIPTION_MAX_LENGTH)
+        return trimmed;
+    const cut = trimmed.slice(0, EXTENDED_DESCRIPTION_MAX_LENGTH);
+    const sentenceEnd = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('! '), cut.lastIndexOf('? '));
+    if (sentenceEnd >= EXTENDED_DESCRIPTION_MIN_LENGTH) {
+        return cut.slice(0, sentenceEnd + 1).replace(/\s+$/, '');
+    }
+    const earlySentenceEnd = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('! '), cut.lastIndexOf('? '));
+    if (earlySentenceEnd >= Math.floor(EXTENDED_DESCRIPTION_MIN_LENGTH / 2)) {
+        return cut.slice(0, earlySentenceEnd + 1).replace(/\s+$/, '');
+    }
+    const lastSpace = cut.lastIndexOf(' ');
+    let safe = lastSpace > EXTENDED_DESCRIPTION_MAX_LENGTH - 60 ? cut.slice(0, lastSpace) : cut;
+    safe = stripTrailingStopWordsAndPunctuation(safe);
+    return safe;
+}
+/**
+ * Clamp a title to `TITLE_MAX_LENGTH` characters in the same
+ * word-boundary-preserving fashion as {@link truncateDescription}.
+ *
+ * **No mid-sentence ellipsis.** When the title overruns the budget and
+ * no natural clause boundary exists inside the
+ * `[HEADLINE_SOFT_MIN, TITLE_MAX_LENGTH]` window, this function returns
+ * an empty string instead of a mid-sentence `…` truncation. The empty
+ * return tells the caller to fall through to the next tier of the
+ * resolver ladder (template-fallback title with category + date),
+ * producing a complete, scan-friendly title rather than a clipped
+ * editorial fragment. Live-site regression (2026-05): titles such as
+ * `AI Trade Strategy: A Legislative First with Structural…` and
+ * `The European Parliament's 24 standing committees continued…`
+ * were emitted before this guard.
+ *
+ * @param text - Raw title text
+ * @returns Clause-truncated title (no ellipsis), or `''` when no
+ *   editorial clause boundary exists in the window
+ */
+export function truncateTitle(text) {
+    if (text.length <= TITLE_MAX_LENGTH)
+        return text;
+    // Prefer ending at a natural clause boundary inside the
+    // `[HEADLINE_SOFT_MIN, TITLE_MAX_LENGTH]` window so the truncated
+    // title reads as a complete journalistic clause rather than a
+    // mid-sentence prose snippet. Iterate boundaries in priority order;
+    // when a candidate falls in the window, break there and drop the
+    // ellipsis since the result is grammatically complete.
+    const search = text.slice(0, TITLE_MAX_LENGTH);
+    for (const boundary of HEADLINE_CLAUSE_BOUNDARIES) {
+        const idx = search.lastIndexOf(boundary);
+        if (idx >= HEADLINE_SOFT_MIN) {
+            const clean = stripTrailingStopWordsAndPunctuation(text.slice(0, idx));
+            if (clean.length >= HEADLINE_SOFT_MIN)
+                return clean;
+        }
+    }
+    // Second-tier fallback: when nothing landed in the soft window, look
+    // for the strongest boundary (`: ` or ` — `) inside the harder
+    // `[HEADLINE_HARD_MIN, HEADLINE_SOFT_MIN]` floor. This rescues
+    // Reader-Briefing-style ledes like
+    // `Immediate priority: DMA enforcement — …` whose clauses cluster in
+    // the opening 30-60 chars, while still keeping the soft-min guard
+    // active for runaway prose. We restrict the boundary set to `: ` and
+    // ` — ` (the two strongest semantic breaks) to avoid emitting trivial
+    // comma-split or full-stop-split fragments from short prose.
+    const STRONG_BOUNDARIES = [': ', ' — ', ' – '];
+    for (const boundary of STRONG_BOUNDARIES) {
+        const idx = search.indexOf(boundary);
+        if (idx >= HEADLINE_HARD_MIN && idx < HEADLINE_SOFT_MIN) {
+            const clean = stripTrailingStopWordsAndPunctuation(text.slice(0, idx));
+            if (clean.length >= HEADLINE_HARD_MIN)
+                return clean;
+        }
+    }
+    // No clause boundary in either window — refuse to emit a mid-sentence
+    // truncation. Caller falls through to template-fallback composition.
+    return '';
+}
+// ────────────────────────────────────────────────────────────────────────
+// Sentence extraction
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * Return the first complete sentence from a prose paragraph, suitable
+ * for use as a fallback editorial title when the artefact H1 is
+ * categorical (e.g. `# EU Parliament Committee Reports`) and the
+ * resolver must derive `<title>` from the BLUF / lede summary instead.
+ *
+ * A "sentence" is the prefix up to the first sentence-terminator
+ * (`. `, `! `, `? `, `; `) inside the `[HEADLINE_SOFT_MIN,
+ * TITLE_MAX_LENGTH]` window. Common abbreviations (`Q1.`, `Q2.`,
+ * `H1.`, `H2.`, `Mr.`, `Mrs.`, `e.g.`, `i.e.`, `vs.`) are skipped
+ * so they don't terminate the sentence prematurely. When no
+ * acceptable terminator exists in the window, returns `''` so the
+ * resolver falls through to the next tier instead of feeding an
+ * over-budget paragraph into {@link truncateTitle} (which would also
+ * return `''`).
+ *
+ * @param paragraph - Prose paragraph (post-`stripInlineMarkdown`)
+ * @returns First sentence, or `''` when none can be identified within
+ *   the soft-min window
+ */
+export function extractFirstSentence(paragraph) {
+    const trimmed = paragraph.trim();
+    if (trimmed.length <= HEADLINE_SOFT_MIN)
+        return trimmed;
+    // Limit terminator search to TITLE_MAX_LENGTH * 1.5 — beyond that
+    // we'd rather let truncateTitle clause-truncate the original
+    // paragraph than return a too-long first sentence.
+    const window = trimmed.slice(0, Math.floor(TITLE_MAX_LENGTH * 1.5));
+    // Skip common abbreviations that contain a period inside a token
+    // (Q1., e.g., i.e., vs., Mr., Mrs., No., U.S., E.U.). We walk
+    // candidate terminator positions; a position counts only when the
+    // char before it is *not* part of a known abbreviation token.
+    const terminators = ['. ', '! ', '? ', '; '];
+    let bestIdx = -1;
+    for (const t of terminators) {
+        let from = HEADLINE_SOFT_MIN;
+        let idx;
+        while ((idx = window.indexOf(t, from)) !== -1) {
+            if (!isAbbreviationBoundary(window, idx) && idx < window.length - 1) {
+                if (bestIdx === -1 || idx < bestIdx)
+                    bestIdx = idx;
+                break;
+            }
+            from = idx + t.length;
+        }
+    }
+    if (bestIdx >= HEADLINE_SOFT_MIN) {
+        return trimmed.slice(0, bestIdx + 1).trim();
+    }
+    // No sentence terminator inside the window — return `''` so the
+    // resolver falls through to the next tier instead of feeding a full
+    // paragraph into {@link truncateTitle} (which would now return `''`
+    // anyway). Being explicit here keeps the tier-1/2 split obvious.
+    return '';
+}
+/**
+ * Check whether the character preceding the `.` at `idx` in `text`
+ * indicates an abbreviation (so the `.` is not a sentence terminator).
+ * Matches the {@link ABBREVIATION_PREFIXES} table and the all-caps
+ * single-letter initials pattern (`U.S.`, `E.U.`).
+ *
+ * @param text - Source text (lowercased segment + original mixed-case)
+ * @param idx - Index of the `.` character in `text`
+ * @returns `true` when the period at `idx` is part of an abbreviation
+ */
+function isAbbreviationBoundary(text, idx) {
+    // All-caps single-letter initial like `U.S.` or `E.U.` — char at
+    // idx-1 is a capital letter, and idx-2 is either start of string,
+    // whitespace, or another single-letter+period pair.
+    if (idx >= 1) {
+        const prev = text.charCodeAt(idx - 1);
+        const isUpperLetter = prev >= 65 && prev <= 90;
+        if (isUpperLetter && (idx === 1 || text[idx - 2] === ' ' || text[idx - 2] === '.')) {
+            return true;
+        }
+    }
+    // ABBREVIATION_PREFIXES lookup — scan backwards from `.` to find the
+    // start of the word, then compare lowercased.
+    let start = idx;
+    while (start > 0 && /[a-zA-Z]/u.test(text[start - 1] ?? ''))
+        start--;
+    const token = text.slice(start, idx + 1).toLowerCase();
+    return ABBREVIATION_PREFIXES.includes(token);
+}
+//# sourceMappingURL=text-truncate.js.map

package/scripts/aggregator/metadata/text-utils-constants.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module Aggregator/Metadata/TextUtilsConstants
+ * @description Shared byte-budget constants and vocabularies used by
+ * the metadata text helpers. Extracted from `text-utils.ts` so the
+ * truncation/extraction helpers can live in `text-truncate.ts`
+ * without creating a circular import — both modules import from
+ * here, and `text-utils.ts` re-exports the truncators for back-compat
+ * with existing call-sites.
+ *
+ * **No imports.** This is a pure leaf module: only constants and
+ * vocabularies, no functions, no I/O.
+ */
+/** Maximum `<meta description>` length we will emit. */
+export declare const DESCRIPTION_MAX_LENGTH = 180;
+/**
+ * Maximum `og:description` / `twitter:description` length we will
+ * emit. Facebook truncates at ~300 characters in the preview card;
+ * Twitter at ~200. We aim for the longer cap so LinkedIn / Slack
+ * (which use the full OG payload) get the full BLUF context, then
+ * let Twitter clip naturally. Below this length the extended
+ * description is emitted verbatim; above it we sentence-boundary
+ * truncate.
+ */
+export declare const EXTENDED_DESCRIPTION_MAX_LENGTH = 300;
+/** Target minimum extended-description length before we even emit it. */
+export declare const EXTENDED_DESCRIPTION_MIN_LENGTH = 200;
+/** Target minimum `<meta description>` length before we append context. */
+export declare const DESCRIPTION_MIN_LENGTH = 140;
+/**
+ * Length below which a raw description is considered too short to stand
+ * on its own and gets enriched with date/context. Independent from
+ * {@link DESCRIPTION_MIN_LENGTH} (which controls sentence-boundary
+ * truncation behaviour). Set lower than DESCRIPTION_MIN_LENGTH so a
+ * clean 100-140 char prose lede is preserved verbatim instead of being
+ * padded with date/context boilerplate.
+ */
+export declare const ENRICHMENT_TRIGGER_LENGTH = 100;
+/** Maximum `<title>` length — anything longer is truncated with an ellipsis. */
+export declare const TITLE_MAX_LENGTH = 140;
+/**
+ * Soft target for headline-style titles produced as a fallback from
+ * BLUF/lede prose. When the candidate exceeds `TITLE_MAX_LENGTH`, the
+ * truncator first looks for a natural clause boundary
+ * (`.`, `:`, `—`, `;`) inside the `[HEADLINE_SOFT_MIN, TITLE_MAX_LENGTH]`
+ * window and breaks there instead of mid-clause-with-ellipsis. This
+ * turns a 137-character truncated prose paragraph into a complete
+ * journalistic clause, which scans much better in news cards and SERP
+ * snippets without sacrificing the keyword-rich opening.
+ */
+export declare const HEADLINE_SOFT_MIN = 60;
+/**
+ * Lower floor for clause-boundary acceptance when the soft-min window
+ * returns nothing. Used by {@link truncateTitle} as a second-tier
+ * fallback: when a long prose paragraph has its only natural clause
+ * boundaries (`: `, ` — `) clustered in the opening 30-60 characters
+ * (typical of Reader-Briefing-style ledes like `Immediate priority:
+ * DMA enforcement — …`), accept the strongest such boundary rather
+ * than fall through to template-fallback composition. This keeps
+ * scan-friendly editorial fragments intact while still rejecting
+ * fragments shorter than a typical news-card title.
+ */
+export declare const HEADLINE_HARD_MIN = 30;
+/**
+ * Punctuation marks that signal a natural clause boundary inside a
+ * BLUF / lede paragraph. Listed in preferred-break order: a colon or
+ * em-dash that introduces a list of consequences is the best break,
+ * full stops are next, and semicolons last. Single ASCII space is
+ * always a fallback boundary handled separately.
+ */
+export declare const HEADLINE_CLAUSE_BOUNDARIES: readonly string[];
+/**
+ * Emoji-banner prefixes that Stage-B agents use to decorate metadata rows
+ * (e.g. `📋 Analysis Owner:`). Any line starting with one of these is
+ * metadata, never prose.
+ */
+export declare const EMOJI_BANNER_CHARS: string[];
+/**
+ * Label prefixes that a prose description must never start with. Every
+ * entry matches case-insensitively at the start of a trimmed line, followed
+ * by optional space and a colon.
+ */
+export declare const METADATA_LINE_PREFIXES: readonly string[];
+/** Connector / determiner words that read as broken copy when they are
+ *  the final token before a truncation ellipsis. */
+export declare const TRAILING_STOP_WORDS: Set<string>;
+/** Trailing characters we always strip before appending our own ellipsis,
+ *  so we never emit double-ellipsis or stray punctuation. */
+export declare const TRAILING_PUNCT: RegExp;
+/**
+ * Abbreviation tokens (lowercase, including the trailing period) that
+ * should NOT count as sentence terminators when `extractFirstSentence`
+ * scans for a `.` boundary. Single-letter all-caps initials
+ * (`U.S.`, `E.U.`) are handled by the all-caps-initial check.
+ */
+export declare const ABBREVIATION_PREFIXES: readonly string[];
+//# sourceMappingURL=text-utils-constants.d.ts.map