Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 | 13x 6x 6x 3x 3x 1x 1x 2x 2x 1x 1x 10x 10x 16x 16x 16x 11x 10x 10x 10x 10x 16x 13x 5x 1x 4x 1x 5x 10x 16x 6x 3x 2x 2x 1x 1x 3x 3x 1x 2x 1x 1x 1x 1x 11x 11x 9x 9x 1x 2x 2x 2x 19x 19x 19x 19x 19x 19x 19x 19x 19x 19x 19x 19x 19x 19x 19x 4x 4x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 4x 4x 4x 19x 19x 9x 11x 11x 10x 10x 781x 781x 781x 436x 436x 436x 345x 1011x 10x 10x 252x 10x 436x 436x 436x 436x 262x 436x 436x 436x 45x 45x 4x 4x 7x 7x 7x 7x 4x 3x 3x 3x 3x 3x 3x 4x 4x 4x 4x 4x 3x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 9x 18x 1x 9x 1x 1x 1x 1x 1x 1x | // SPDX-FileCopyrightText: 2024-2026 Hack23 AB
// SPDX-License-Identifier: Apache-2.0
/**
* @module Aggregator/ArticleGenerator
* @description CLI entry point for the analysis-artifact-driven article
* pipeline. Given a run directory under `analysis/daily/`, it aggregates
* every artifact into a canonical Markdown document, renders it to HTML,
* and writes one HTML variant per language (plus the English source
* Markdown).
*
* 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"
*
* Designed to be idempotent: running again with no changes overwrites
* identical files byte-for-byte.
*/
import fs from 'fs';
import path from 'path';
import { pathToFileURL } from 'url';
import { aggregateAnalysisRun, type AggregatedRun } from './analysis-aggregator.js';
import {
resolveArticleMetadata,
extractStrongProseLine,
type MetadataManifest,
type ResolvedMetadata,
} from './article-metadata.js';
import { renderMarkdown } from './markdown-renderer.js';
import { wrapArticleHtml, getArticleFilename } from './article-html.js';
import { ALL_LANGUAGES } from '../constants/language-core.js';
import type { LanguageCode } from '../types/index.js';
/** Parsed CLI arguments. */
export interface CliOptions {
/**
* Absolute path to a single analysis run directory, or `null` when
* operating in `--all` mode (batch over every discovered run).
*/
readonly runDir: string | null;
/**
* Batch mode: when `true`, walk `analysis/daily/**\/manifest.json` and
* render every run that has a valid `articleType` in its manifest.
*/
readonly all: boolean;
/**
* Optional lower bound (inclusive) on the `YYYY-MM-DD` run date when
* `all === true`. Runs whose manifest `date` (or directory-derived date)
* is earlier are skipped.
*/
readonly since?: string;
/** Languages to render (defaults to all 14). */
readonly langs: readonly LanguageCode[];
/** Output directory for HTML files (defaults to `news/`). */
readonly outDir: string;
/** Repo root used for relative path computation. */
readonly repoRoot: string;
/** Optional: override the auto-derived article title (single-run only). */
readonly title?: string;
/** 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.
*/
readonly markdownOnly: boolean;
}
/** Result summary returned by {@link generateArticle}. */
export interface GenerateResult {
/** Repo-relative path of the English source Markdown that was written. */
readonly sourceMarkdownRelPath: string;
/** Filenames written under `outDir`, relative to `outDir`. */
readonly writtenFiles: readonly string[];
/** Metadata from {@link aggregateAnalysisRun}. */
readonly aggregated: AggregatedRun;
}
/**
* Parse a flat list of CLI args (no node/script entries) into {@link CliOptions}.
* Supports `--flag value` and `--flag=value` styles, and repeatable `--lang`.
*
* @param argv - Argument list, typically `process.argv.slice(2)`
* @param repoRoot - Absolute repo root used to resolve default output paths
* @returns Fully-populated {@link CliOptions} ready for {@link generateArticle}
*/
/** Mutable accumulator backing {@link parseCliArgs}. */
interface CliParseAccumulator {
runDir: string | null;
all: boolean;
since?: string;
langs: LanguageCode[];
outDir: string;
title?: string;
description?: string;
markdownOnly: boolean;
}
/**
* Fold one parsed {@link FlagResult} into the accumulator. Split out so
* {@link parseCliArgs} stays under the cognitive-complexity budget.
*
* @param acc - Mutable accumulator
* @param result - Parsed flag result
*/
function applyFlagResult(acc: CliParseAccumulator, result: FlagResult): void {
switch (result.kind) {
case 'runDir':
acc.runDir = result.value;
return;
case 'all':
acc.all = true;
return;
case 'since':
acc.since = result.value;
return;
case 'lang':
acc.langs.push(result.value);
return;
case 'outDir':
acc.outDir = result.value;
return;
case 'title':
acc.title = result.value;
return;
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.
const exhaustive: never = result;
throw new Error(`Unhandled flag result: ${JSON.stringify(exhaustive)}`);
}
}
}
export function parseCliArgs(argv: readonly string[], repoRoot: string): CliOptions {
const acc: CliParseAccumulator = {
runDir: null,
all: false,
langs: [],
outDir: path.join(repoRoot, 'news'),
markdownOnly: false,
};
for (let i = 0; i < argv.length; i++) {
const arg = argv[i] ?? '';
const [flag, inlineValue] = arg.includes('=') ? splitFlag(arg) : [arg, undefined];
const takeValue = (): string => {
if (inlineValue !== undefined) return inlineValue;
const next = argv[i + 1];
Iif (next === undefined) {
throw new Error(`Missing value for ${flag}`);
}
i++;
return next;
};
applyFlagResult(acc, applyCliFlag(flag, takeValue));
}
if (!acc.all) {
if (!acc.runDir) {
throw new Error('--run <path> or --all is required');
}
if (!fs.existsSync(acc.runDir)) {
throw new Error(`Run directory does not exist: ${acc.runDir}`);
}
}
const opts: CliOptions = {
runDir: acc.runDir,
all: acc.all,
langs: acc.langs.length > 0 ? acc.langs : [...ALL_LANGUAGES],
outDir: acc.outDir,
repoRoot,
markdownOnly: acc.markdownOnly,
...(acc.since !== undefined ? { since: acc.since } : {}),
...(acc.title !== undefined ? { title: acc.title } : {}),
...(acc.description !== undefined ? { description: acc.description } : {}),
};
return opts;
}
/**
* Result of applying a single CLI flag. Each kind corresponds to one of
* the accumulator variables in {@link parseCliArgs}. Extracted so the main
* parser stays under the cognitive-complexity budget.
*/
type FlagResult =
| { kind: 'runDir'; value: string }
| { kind: 'all' }
| { kind: 'since'; value: string }
| { kind: 'lang'; value: LanguageCode }
| { kind: 'outDir'; value: string }
| { kind: 'title'; value: string }
| { kind: 'description'; value: string }
| { kind: 'markdownOnly' };
/**
* Resolve one CLI flag to a {@link FlagResult}. Throws `Error` for any
* unsupported flag or language code.
*
* @param flag - Flag name (e.g. `--run`)
* @param takeValue - Lazily returns the value argument for value-bearing flags
* @returns Parsed {@link FlagResult}
*/
function applyCliFlag(flag: string, takeValue: () => string): FlagResult {
switch (flag) {
case '--run':
case '--analysis-dir':
return { kind: 'runDir', value: path.resolve(takeValue()) };
case '--all':
return { kind: 'all' };
case '--since': {
const value = takeValue();
if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
throw new Error(`--since expects a YYYY-MM-DD date, got: ${value}`);
}
return { kind: 'since', value };
}
case '--lang':
case '--language': {
const value = takeValue();
if (!ALL_LANGUAGES.includes(value as LanguageCode)) {
throw new Error(`Unsupported language code: ${value}`);
}
return { kind: 'lang', value: value as LanguageCode };
}
case '--out-dir':
case '--output':
return { kind: 'outDir', value: path.resolve(takeValue()) };
case '--title':
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
default:
throw new Error(`Unknown argument: ${flag}`);
}
}
/**
* Split `--flag=value` into `["--flag", "value"]`.
*
* @param arg - Raw argument in `--flag=value` form
* @returns Tuple of `[flag, value]`
*/
function splitFlag(arg: string): [string, string] {
const eq = arg.indexOf('=');
return [arg.slice(0, eq), arg.slice(eq + 1)];
}
/**
* Print CLI help text to stdout.
*/
function printHelp(): void {
process.stdout.write(
[
'Usage:',
' generate-article --run <path> [options]',
' 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.',
'',
'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')
);
}
/**
* Build the article slug `YYYY-MM-DD-<article-type>[-<runSuffix>]`.
*
* @param date - ISO date string (`YYYY-MM-DD`)
* @param articleType - Article-type slug (e.g. `breaking`)
* @param runSuffix - Optional collision-suffix (e.g. `run191`) appended when
* multiple runs share the same (date, articleType) pair
* @returns Combined slug used as the file-stem for every language variant
*/
export function buildArticleSlug(date: string, articleType: string, runSuffix?: string): string {
const base = `${date}-${articleType}`;
return runSuffix ? `${base}-${runSuffix}` : base;
}
/**
* Turn an arbitrary run-id string into a short, filename-safe suffix.
* Keeps ASCII word/dash characters only and caps the length at 32 to avoid
* filesystem-path-length surprises.
*
* @param runId - Raw run identifier from the manifest (or directory name)
* @returns Sanitised suffix usable in a filename
*/
export function sanitizeRunSuffix(runId: string): string {
const cleaned = runId.replace(/[^\w.-]+/g, '-').replace(/^-+|-+$/g, '');
return cleaned.slice(0, 32) || 'run';
}
/**
* Return `true` when a line should be skipped when hunting for the default
* description. Thin wrapper preserved for back-compat — real logic lives
* in `src/aggregator/article-metadata.ts`'s `shouldSkipDescriptionLine`.
*
* @param line - Trimmed line from the aggregated Markdown source
* @returns `true` when the line is not prose and should be skipped
*/
function shouldSkipDescriptionLine(line: string): boolean {
if (line.length === 0) return true;
if (line.startsWith('#')) return true;
if (line.startsWith('>')) return true;
if (line.startsWith('<')) return true;
if (line.startsWith('|')) return true;
return false;
}
/** Description used when no prose paragraph qualifies. */
const FALLBACK_DESCRIPTION =
'EU Parliament intelligence summary derived from committed analysis artifacts.';
/**
* Extract a short description from the first prose paragraph of the
* aggregated Markdown — used as the default `<meta name="description">`.
* Uses the stricter `extractStrongProseLine` filter from
* `article-metadata.ts` so mermaid `%%{init}` blocks, `title …` directives,
* emoji-banner metadata rows, and `Analysis Date:` / `Run:` / `Window:`
* style banners no longer leak into `<meta description>`. Kept as an
* exported thin wrapper for back-compat with the existing test suite.
*
* @param markdown - Aggregated Markdown document
* @returns Plain-text description, truncated to ≤300 characters
*/
export function extractDefaultDescription(markdown: string): string {
// Suppress unused warning: keep `shouldSkipDescriptionLine` for any
// legacy consumer importing it transitively.
void shouldSkipDescriptionLine;
const strong = extractStrongProseLine(markdown);
return strong.length > 0 ? strong : FALLBACK_DESCRIPTION;
}
/**
* Render a single language-variant article. Pulls from a pre-translated
* `<slug>.<lang>.md` file when it exists, otherwise renders the English
* aggregate. Extracted from {@link generateArticle} so the outer function
* stays under the cognitive-complexity budget.
*
* @param lang - Target language code
* @param slug - Article slug (`<date>-<type>`)
* @param aggregated - Aggregated-run metadata
* @param englishHtml - Pre-rendered HTML of the English aggregate
* @param chromeOptions - Shared chrome options
* @param chromeOptions.metadata - Per-language `{title, description}` map
* resolved by {@link resolveArticleMetadata}
* @param chromeOptions.sourceMarkdownRelPath - Repo-relative path of the
* canonical English Markdown source written by the same run
* @param chromeOptions.articleCount - Total article count surfaced in the
* site footer's `<p class="footer-stats">…</p>` line
* @param opts - CLI options (needed for `outDir`)
* @returns Relative filename of the HTML file written
*/
function writeLanguageVariant(
lang: LanguageCode,
slug: string,
aggregated: AggregatedRun,
englishHtml: string,
chromeOptions: {
metadata: ResolvedMetadata;
sourceMarkdownRelPath: string;
articleCount: number;
},
opts: CliOptions
): string {
const langMdFilename = `${slug}.${lang}.md`;
const langMdAbs = path.join(opts.outDir, langMdFilename);
let bodyHtml = englishHtml;
let metaSource = aggregated.markdown;
Iif (lang !== 'en' && fs.existsSync(langMdAbs)) {
metaSource = fs.readFileSync(langMdAbs, 'utf8');
bodyHtml = renderMarkdown(metaSource).html;
}
// 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
// translations of the headline are a future enhancement tracked as
// out-of-scope).
const entry = getMetadataEntry(chromeOptions.metadata, lang);
const perLangDescription =
lang !== 'en' && metaSource !== aggregated.markdown
? extractStrongProseLine(metaSource) || entry.description
: entry.description;
const html = wrapArticleHtml({
lang,
articleSlug: slug,
body: bodyHtml,
title: entry.title,
description: perLangDescription,
date: aggregated.date,
articleType: aggregated.articleType,
sourceMarkdownRelPath: chromeOptions.sourceMarkdownRelPath,
toc: aggregated.sectionToc,
articleCount: chromeOptions.articleCount,
});
const filename = getArticleFilename(slug, lang);
fs.writeFileSync(path.join(opts.outDir, filename), html, 'utf8');
return filename;
}
/**
* Safely look up one language entry in a {@link ResolvedMetadata} map.
* The runtime shape is always complete (one entry per language), but the
* access goes via `Object.getOwnPropertyDescriptor` to satisfy ESLint's
* `security/detect-object-injection` rule.
*
* @param map - Resolved per-language metadata
* @param lang - Target language code
* @returns The entry for `lang` (always populated by
* {@link resolveArticleMetadata})
*/
function getMetadataEntry(
map: ResolvedMetadata,
lang: LanguageCode
): { readonly title: string; readonly description: string } {
const descriptor = Object.getOwnPropertyDescriptor(map, lang);
Eif (descriptor?.value) {
return descriptor.value as { readonly title: string; readonly description: string };
}
const en = Object.getOwnPropertyDescriptor(map, 'en')?.value as
| { readonly title: string; readonly description: string }
| undefined;
return en ?? { title: '', description: '' };
}
/**
* Count the number of articles the site currently publishes, derived
* from `analysis/daily/**` runs with a valid `articleType` — the same
* set that `npm run generate-article:all` would materialise. Using the
* analysis-run catalogue (rather than the `<outDir>` filesystem) keeps
* the derived count stable across repeated invocations of
* {@link generateArticle}, preserving determinism for reproducible-build
* tests and preventing the footer from drifting as a batch run
* progresses.
*
* @param repoRoot - Absolute path to the repository root
* @returns Non-negative article count (zero when the analysis tree is empty)
*/
function countPublishedArticles(repoRoot: string): number {
try {
return discoverAnalysisRuns(repoRoot).length;
} catch {
return 0;
}
}
/**
* Run the full aggregate → render → write pipeline for one run.
*
* @param opts - Fully-populated {@link CliOptions} (typically from
* {@link parseCliArgs}) — must have a non-null `runDir`
* @param runSuffix - Optional collision-suffix appended to the slug when
* multiple runs share the same (date, articleType) pair in batch mode
* @param articleCountOverride - Optional total article count to surface in
* the footer's `<p class="footer-stats">…</p>`. When omitted the
* count is derived from `<outDir>/*-en.html` — accurate for single
* runs but misleading mid-batch, so {@link generateAllArticles}
* passes the final total here.
* @returns Summary of the generated artefacts ({@link GenerateResult})
*/
export function generateArticle(
opts: CliOptions,
runSuffix?: string,
articleCountOverride?: number
): GenerateResult {
Iif (!opts.runDir) {
throw new Error('generateArticle: runDir is required');
}
const aggregated = aggregateAnalysisRun({
runDir: opts.runDir,
repoRoot: opts.repoRoot,
});
const slug = buildArticleSlug(aggregated.date, aggregated.articleType, runSuffix);
// Resolve per-language {title, description} from the real article
// content (manifest override → artefact H1 → aggregated H1 → strong
// prose → localized template). This replaces the previous
// `defaultTitle()` + `extractDefaultDescription()` approach which
// produced boring, repeated metadata.
const manifestMetadata = readManifestMetadata(opts.runDir);
const resolvedMetadata = resolveArticleMetadata({
articleType: aggregated.articleType,
date: aggregated.date,
markdown: aggregated.markdown,
manifest: manifestMetadata,
runDir: opts.runDir,
});
// CLI `--title` / `--description` overrides still win over everything
// (used by ad-hoc curator runs and by the existing test suite).
const effectiveMetadata: ResolvedMetadata =
opts.title || opts.description
? applyCliOverrides(resolvedMetadata, opts.title, opts.description)
: resolvedMetadata;
// Write source Markdown under <outDir>/<slug>.en.md for transparency.
ensureDir(opts.outDir);
const sourceMdFilename = `${slug}.en.md`;
const sourceMdAbs = path.join(opts.outDir, sourceMdFilename);
fs.writeFileSync(sourceMdAbs, aggregated.markdown, 'utf8');
const sourceMdRelPath = path.relative(opts.repoRoot, sourceMdAbs).split(path.sep).join('/');
const written: string[] = [sourceMdFilename];
if (!opts.markdownOnly) {
const rendered = renderMarkdown(aggregated.markdown);
const chromeOptions = {
metadata: effectiveMetadata,
sourceMarkdownRelPath: sourceMdRelPath,
articleCount: articleCountOverride ?? countPublishedArticles(opts.repoRoot),
};
for (const lang of opts.langs) {
const filename = writeLanguageVariant(
lang,
slug,
aggregated,
rendered.html,
chromeOptions,
opts
);
written.push(filename);
}
}
return { sourceMarkdownRelPath: sourceMdRelPath, writtenFiles: written, aggregated };
}
/** Candidate run discovered under `analysis/daily/`. */
export interface DiscoveredRun {
/** Absolute run directory path. */
readonly runDir: string;
/** Article type from the manifest (never `"unknown"`). */
readonly articleType: string;
/** Run date resolved from the manifest or directory name. */
readonly date: string;
/** Run identifier from the manifest, or the directory basename. */
readonly runId: string;
}
/**
* Walk `analysis/daily/` recursively and return every subdirectory that
* contains a `manifest.json` with a non-empty, non-`unknown` `articleType`.
* Runs missing a manifest or carrying a default `articleType` are skipped
* so batch runs don't emit garbage articles like
* `2026-04-13-unknown-en.html`.
*
* @param repoRoot - Absolute repository root
* @returns Sorted list of discovered runs (oldest date first, then lexical)
*/
export function discoverAnalysisRuns(repoRoot: string): DiscoveredRun[] {
const root = path.join(repoRoot, 'analysis', 'daily');
if (!fs.existsSync(root)) return [];
const results: DiscoveredRun[] = [];
const walk = (dir: string): void => {
const entries = fs.readdirSync(dir, { withFileTypes: true });
// If this dir has a manifest, consider it a run and do not descend.
const manifestPath = path.join(dir, 'manifest.json');
if (fs.existsSync(manifestPath)) {
const run = readRunCandidate(dir, manifestPath);
if (run) results.push(run);
return;
}
for (const entry of entries) {
if (entry.isDirectory()) walk(path.join(dir, entry.name));
}
};
walk(root);
results.sort((a, b) =>
a.date === b.date ? a.runDir.localeCompare(b.runDir) : a.date.localeCompare(b.date)
);
return results;
}
/**
* Read and validate the manifest for a candidate run directory.
*
* @param runDir - Absolute path of the candidate directory
* @param manifestPath - Absolute path of its `manifest.json`
* @returns {@link DiscoveredRun} when the manifest declares a valid
* article type, `null` otherwise (silently skipped by `--all`)
*/
function readRunCandidate(runDir: string, manifestPath: string): DiscoveredRun | null {
let parsed: Record<string, unknown>;
try {
parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as Record<string, unknown>;
} catch {
return null;
}
const articleType = typeof parsed.articleType === 'string' ? parsed.articleType : '';
if (!articleType || articleType === 'unknown') return null;
const dateFromManifest = typeof parsed.date === 'string' ? parsed.date : '';
const date = /^\d{4}-\d{2}-\d{2}$/.test(dateFromManifest)
? dateFromManifest
: dateFromRunPath(runDir);
const runId =
typeof parsed.runId === 'string' && parsed.runId ? parsed.runId : path.basename(runDir);
return { runDir, articleType, date, runId };
}
/**
* Pull the `YYYY-MM-DD` date from a run-dir path segment. Falls back to the
* epoch date when no ISO date is embedded.
*
* @param runDir - Absolute run directory path
* @returns ISO date string
*/
function dateFromRunPath(runDir: string): string {
const match = /(\d{4}-\d{2}-\d{2})/.exec(runDir);
return match ? (match[1] ?? '1970-01-01') : '1970-01-01';
}
/**
* Group discovered runs by `(date, articleType)` so callers can decide
* whether a collision-suffix is needed when writing articles.
*
* @param runs - Discovered runs
* @returns Map from `"<date>|<articleType>"` to the runs in that group
*/
export function groupRunsForCollision(
runs: readonly DiscoveredRun[]
): Map<string, DiscoveredRun[]> {
const groups = new Map<string, DiscoveredRun[]>();
for (const run of runs) {
const key = `${run.date}|${run.articleType}`;
const bucket = groups.get(key) ?? [];
bucket.push(run);
groups.set(key, bucket);
}
return groups;
}
/**
* Batch-generate articles for every discovered run. Runs that share a
* `(date, articleType)` pair are disambiguated by appending the sanitised
* `runId` as a slug suffix so none of the language variants are ever
* silently overwritten.
*
* @param opts - CLI options (must have `all: true`)
* @returns Per-run generation results in the order they were processed
*/
export function generateAllArticles(opts: CliOptions): GenerateResult[] {
const allRuns = discoverAnalysisRuns(opts.repoRoot);
const filtered = opts.since ? allRuns.filter((r) => r.date >= (opts.since as string)) : allRuns;
const groups = groupRunsForCollision(filtered);
const results: GenerateResult[] = [];
// Pre-compute the total article count so every footer in the batch
// surfaces a stable number rather than the directory size at the moment
// each run is rendered (which would grow from 0 → N during the batch).
const articleCountOverride = filtered.length;
for (const run of filtered) {
const key = `${run.date}|${run.articleType}`;
const bucket = groups.get(key) ?? [];
const suffix = bucket.length > 1 ? sanitizeRunSuffix(run.runId) : undefined;
const runOpts: CliOptions = { ...opts, runDir: run.runDir };
results.push(generateArticle(runOpts, suffix, articleCountOverride));
}
return results;
}
/**
* Read the raw manifest.json from a run directory and return the subset
* of fields consumed by {@link resolveArticleMetadata}. Returns an empty
* object when the manifest is missing or unreadable so the resolver
* simply falls through to the artefact / aggregator tiers.
*
* @param runDir - Absolute run directory path
* @returns Metadata-relevant manifest fields (never `undefined`)
*/
function readManifestMetadata(runDir: string): MetadataManifest {
const manifestPath = path.join(runDir, 'manifest.json');
Iif (!fs.existsSync(manifestPath)) return {};
try {
const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as Record<string, unknown>;
const manifest: MetadataManifest = {};
Eif (typeof parsed.articleType === 'string') {
Object.assign(manifest, { articleType: parsed.articleType });
}
Eif (typeof parsed.date === 'string') {
Object.assign(manifest, { date: parsed.date });
}
Eif (typeof parsed.runId === 'string') {
Object.assign(manifest, { runId: parsed.runId });
}
Iif (typeof parsed.title === 'string' || isLanguageMapLike(parsed.title)) {
Object.assign(manifest, { title: parsed.title });
}
Iif (typeof parsed.description === 'string' || isLanguageMapLike(parsed.description)) {
Object.assign(manifest, { description: parsed.description });
}
Iif (typeof parsed.committee === 'string') {
Object.assign(manifest, { committee: parsed.committee });
}
return manifest;
} catch {
return {};
}
}
/**
* Shallow-check that a value looks like a `LanguageMap<string>` without
* pulling in the full `LanguageCode` list at the runtime import site.
*
* @param value - Arbitrary JSON value
* @returns `true` when `value` is a plain object with string values
*/
function isLanguageMapLike(value: unknown): value is Record<string, string> {
Eif (!value || typeof value !== 'object' || Array.isArray(value)) return false;
for (const entry of Object.values(value as Record<string, unknown>)) {
if (typeof entry !== 'string') return false;
}
return true;
}
/**
* Apply ad-hoc CLI `--title` / `--description` overrides on top of the
* resolver output. Overrides are applied to every language so the operator
* can hand-author a single headline for a one-off run without having to
* know which language variant they're working in.
*
* @param base - Resolver output
* @param titleOverride - CLI `--title` value, if any
* @param descriptionOverride - CLI `--description` value, if any
* @returns Metadata with overrides applied uniformly across languages
*/
function applyCliOverrides(
base: ResolvedMetadata,
titleOverride: string | undefined,
descriptionOverride: string | undefined
): ResolvedMetadata {
const result: Record<LanguageCode, { readonly title: string; readonly description: string }> =
Object.create(null) as Record<
LanguageCode,
{ readonly title: string; readonly description: string }
>;
for (const lang of ALL_LANGUAGES) {
const entry = getMetadataEntry(base, lang);
Object.defineProperty(result, lang, {
value: {
title: titleOverride ?? entry.title,
description: descriptionOverride ?? entry.description,
},
enumerable: true,
writable: true,
configurable: true,
});
}
return result;
}
/**
* Derive a default article title from the aggregated run metadata.
* Preserved as a thin back-compat wrapper — production callers now go
* through {@link resolveArticleMetadata}.
*
* @param run - Aggregated run metadata
* @returns Human-readable title like `EU Parliament Breaking — 2026-01-15`
*/
function defaultTitle(run: AggregatedRun): string {
const typeLabel = run.articleType
.split(/[-_]/g)
.map((seg) => (seg ? seg.charAt(0).toUpperCase() + seg.slice(1) : seg))
.join(' ')
.trim();
return `EU Parliament ${typeLabel || 'Intelligence'} — ${run.date}`;
}
// Retain the back-compat export even though the in-module callers no
// longer invoke it — some downstream curators import it via the bundled
// `scripts/` output. The `void` reference keeps ESLint's
// `no-unused-vars` happy without an explicit export.
void defaultTitle;
/**
* Create `dir` recursively if it doesn't already exist.
*
* @param dir - Absolute directory path to ensure
*/
function ensureDir(dir: string): void {
Iif (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
}
/**
* Main entry when invoked as a script. Uses `process.argv.slice(2)` and the
* current working directory as repo root unless overridden by `REPO_ROOT`.
*
* @param argv - Argument list (defaults to `process.argv.slice(2)`)
*/
export async function main(argv: readonly string[] = process.argv.slice(2)): Promise<void> {
const repoRoot = process.env.REPO_ROOT ? path.resolve(process.env.REPO_ROOT) : process.cwd();
const opts = parseCliArgs(argv, repoRoot);
if (opts.all) {
const results = generateAllArticles(opts);
let totalFiles = 0;
let totalArtifacts = 0;
for (const r of results) {
totalFiles += r.writtenFiles.length;
totalArtifacts += r.aggregated.includedArtifacts.length;
process.stdout.write(
` [${r.aggregated.date}/${r.aggregated.articleType}] ${r.writtenFiles.length} file(s) · ${r.aggregated.includedArtifacts.length} artifact(s) · gate ${r.aggregated.gateResult}\n`
);
}
process.stdout.write(
`Generated ${totalFiles} file(s) across ${results.length} run(s) from ${totalArtifacts} total artifact(s)\n`
);
return;
}
const result = generateArticle(opts);
process.stdout.write(
`Generated ${result.writtenFiles.length} file(s) from ${result.aggregated.includedArtifacts.length} artifact(s) — gate: ${result.aggregated.gateResult}\n`
);
for (const f of result.writtenFiles) process.stdout.write(` ${f}\n`);
}
// Only run when invoked directly, not when imported by tests.
const isMain = (() => {
const entry = process.argv[1];
Iif (!entry) return false;
try {
return import.meta.url === pathToFileURL(entry).href;
} catch {
return false;
}
})();
Iif (isMain) {
main().catch((err: unknown) => {
const msg = err instanceof Error ? err.message : String(err);
process.stderr.write(`generate-article: ${msg}\n`);
process.exit(1);
});
}
|