Improve architecture, code quality, and test coverage for HTML/XML/RSS/sitemap generation from article.md (render-articles pipeline)

[pethers]

📋 Issue Type

Architecture / Code Quality / Testing

🎯 Objective

Refactor the HTML rendering pipeline (article.md → news/*.html) and all related static output generation (sitemap XML, sitemap HTML, RSS feed, news indexes) into well-architected bounded contexts with strict typing, comprehensive tests, and clear separation of concerns.

📊 Current State

The rendering/publishing pipeline involves multiple scripts with overlapping responsibilities:

HTML Rendering:

• scripts/render-articles.ts — Main renderer (article.md → news/{date}-{type}-{lang}.html)
• scripts/render-lib/article.ts — Article document model
• scripts/render-lib/chrome.ts — HTML chrome/template wrapping
• scripts/render-lib/chrome-i18n.ts — Internationalized chrome strings
• scripts/render-lib/constants.ts — Shared constants
• scripts/render-lib/jsonld.ts — JSON-LD structured data
• scripts/render-lib/url-helpers.ts — URL construction
• scripts/render-lib/article-types.ts — Article type registry
• scripts/render-lib/markdown/ (7 files) — Markdown → HTML pipeline (rehype/remark plugins, Mermaid preprocessing, sanitization)

Supporting Generators:

• scripts/generate-news-indexes/ — News index pages
• scripts/generate-sitemap.ts + scripts/sitemap-xml/ — XML sitemap
• scripts/generate-sitemap-html.ts + scripts/sitemap-html/ — Human-readable sitemap
• scripts/generate-rss.ts + scripts/rss/ — RSS feed
• scripts/generate-political-intelligence.ts — Political intelligence page
• scripts/normalize-static-html-chrome.ts — Chrome normalization
• scripts/backfill-translated-chrome.ts — Translation backfill
• scripts/strip-legacy-chrome-script-tags.ts — Legacy cleanup
• scripts/extract-news-metadata.ts — News metadata extraction
• scripts/html-utils.ts — Shared HTML utilities

Issues:

• Render pipeline mixes concerns: Markdown parsing, HTML templating, i18n, SEO, and sanitization in render-lib/
• Multiple independent scripts for sitemap/RSS/indexes with duplicated HTML generation patterns
• chrome.ts is likely large and handles too many responsibilities (header, footer, nav, SEO meta, language switcher)
• Markdown pipeline in render-lib/markdown/ tightly coupled to rendering rather than being a standalone transformation
• Inconsistent error handling between generators
• Limited test coverage for HTML output correctness (structure, accessibility, valid HTML5)
• No shared "static output writer" abstraction — each generator handles file I/O independently

🚀 Desired State

Architecture (Bounded Contexts)

scripts/rendering/
├── interfaces.ts              # Shared types for all rendering
├── markdown-to-html/          # Pure Markdown → HTML transformation
│   ├── pipeline.ts            # rehype/remark pipeline (compose plugins)
│   ├── plugins/
│   │   ├── mermaid-preprocess.ts
│   │   ├── slug-prefixed.ts
│   │   ├── wrap-tables.ts
│   │   └── sanitize.ts
│   └── index.ts
├── article-chrome/            # HTML page chrome (header/footer/nav)
│   ├── template.ts           # Base HTML5 template
│   ├── header.ts             # Site header with nav
│   ├── footer.ts             # Site footer with sources
│   ├── language-switcher.ts  # hreflang + UI switcher
│   ├── seo.ts                # Meta tags, OG, Twitter Cards
│   ├── jsonld.ts             # JSON-LD structured data
│   └── index.ts
├── i18n/                      # Internationalization for chrome
│   ├── strings.ts            # UI string registry (14 langs)
│   ├── rtl.ts                # RTL layout handling
│   └── index.ts
├── article-renderer/          # Compose markdown + chrome → full page
│   ├── renderer.ts           # Main article rendering
│   └── index.ts
└── index.ts                   # Public API

scripts/static-outputs/
├── interfaces.ts              # Shared types for generators
├── sitemap-xml/               # XML sitemap generation
├── sitemap-html/              # Human-readable sitemap
├── rss/                       # RSS feed generation
├── news-indexes/              # News index pages
├── political-intelligence/    # Political intelligence page
├── writer.ts                  # Shared file writer with validation
└── index.ts

Code Quality

• Clear separation: Markdown transformation is independent of HTML chrome
• Each chrome component (header, footer, nav, SEO) is independently testable
• i18n strings centralized — no scattered translations
• Shared file writer handles I/O, encoding, and validation consistently
• All HTML output validated against HTML5 spec in tests
• No any types — typed interfaces for article metadata, page context, i18n strings

Test Quality

• Each component has unit tests verifying:
  • Correct HTML5 structure output
  • WCAG 2.1 AA compliance (ARIA, contrast, keyboard nav)
  • All 14 language outputs (including RTL for AR/HE)
  • JSON-LD correctness (Schema.org NewsArticle)
  • hreflang alternate links
  • RSS/sitemap XML validity
• Snapshot tests for rendered HTML stability
• Integration tests for full render pipeline
• Link integrity tests for generated cross-references

🔧 Implementation Approach

1. Map current architecture: Document data flow through render-articles.ts → render-lib/ → file output
2. Define interfaces: Type definitions for article context, page metadata, chrome options, i18n strings
3. Separate Markdown pipeline: Extract render-lib/markdown/ into standalone bounded context
4. Decompose chrome: Split chrome.ts into focused components (header, footer, nav, SEO, jsonld)
5. Centralize i18n: Single source of truth for all UI strings across 14 languages
6. Unify static generators: Shared writer + validation for sitemap/RSS/indexes
7. Write comprehensive tests: HTML structure, accessibility, i18n, SEO validation
8. Validate: Ensure all generated HTML/XML/RSS output is identical before/after refactoring

📚 Key Files

File	Purpose
scripts/render-articles.ts	Main article renderer
scripts/render-lib/ (11+ files)	Rendering library
scripts/render-lib/markdown/ (7 files)	Markdown pipeline
scripts/render-lib/aggregator/ (9 files)	Content aggregation
scripts/generate-news-indexes/	News index generation
scripts/generate-sitemap.ts + scripts/sitemap-xml/	XML sitemap
scripts/generate-sitemap-html.ts + scripts/sitemap-html/	HTML sitemap
scripts/generate-rss.ts + scripts/rss/	RSS feed
scripts/generate-political-intelligence.ts	Intelligence page
scripts/html-utils.ts	Shared HTML utilities
scripts/normalize-static-html-chrome.ts	Chrome normalization
scripts/backfill-translated-chrome.ts	Translation backfill
tests/render-lib.test.ts	Existing render tests
tests/render-lib-architecture.test.ts	Architecture tests
tests/generate-rss.test.ts	RSS generation tests
tests/generate-sitemap.test.ts	Sitemap tests
tests/generate-sitemap-html.test.ts	HTML sitemap tests
tests/generate-news-indexes.test.ts	News index tests
Article-Generation.md	System documentation

✅ Acceptance Criteria

• Markdown-to-HTML pipeline is independently testable (no chrome dependency)
• Chrome decomposed into focused components (<200 lines each)
• i18n strings centralized with type-safe access for all 14 languages
• Shared file writer validates output before writing
• All HTML output passes HTML5 validation in tests
• JSON-LD output validates against Schema.org NewsArticle
• RSS output validates against RSS 2.0 spec
• Sitemap XML validates against sitemap.org schema
• Each component has >90% line coverage
• RTL languages (AR, HE) correctly handled in all chrome components
• No any types in rendering code
• Generated output byte-identical before/after refactoring
• All existing tests pass (npm test)
• Article-Generation.md updated to reflect new rendering architecture

🤖 Recommended Agent

code-quality-engineer — Architecture refactoring, HTML/CSS quality, bounded contexts, test coverage

🏷️ Labels

enhancement, refactor, testing, component:content-generation, news-generation, html-css, i18n, priority-high, size-xl

[pethers]

🔗 Related Issues (Architecture & Quality Improvement Series)

This issue is part of a coordinated effort to improve architecture, code quality, and test coverage across the riksdagsmonitor platform:

1. Improve architecture and quality of agentic workflows: extract embedded code, enforce bounded contexts, and add strict-typed TypeScript #2279 — Agentic workflows: extract embedded code, enforce bounded contexts
2. Resolve all ESLint warnings, improve strict typing, fix knip issues, and enhance TypeDoc/reporting configuration #2276 — ESLint warnings, strict typing, knip, TypeDoc/reporting
3. Improve architecture, code quality, and test coverage for article.md generation pipeline (aggregate-analysis → article.md) #2277 — article.md generation pipeline (aggregate-analysis)
4. Improve architecture, code quality, and test coverage for HTML/XML/RSS/sitemap generation from article.md (render-articles pipeline) #2278 — HTML/XML/RSS/sitemap rendering pipeline (render-articles) (this issue)

Dependency order: #2276 (tooling) first, then #2277 (article.md pipeline defines interfaces consumed here), then this issue (#2278) for the rendering/publishing layer.