# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """The changelog the bot announces, read from DOCS-changelog.md. That file is the single source: there is no second machine-readable copy to drift out of sync with it. Only two shapes are recognised -- a `## — ` heading and a `- ` bullet beneath one -- so prose around them is free. """ from __future__ import annotations import re from dataclasses import dataclass from pathlib import Path from typing import Final from signal_bot.versioning import Pope, ordinal_for, pope_for # Repo root, since the changelog is documentation rather than package data. DEFAULT_PATH: Final = Path(__file__).resolve().parent.parent / "DOCS-changelog.md" _HEADING: Final = re.compile(r"^##\s+(\d+\.\d+\.\d+)\s*[—-]\s*(.+?)\s*$") _BULLET: Final = re.compile(r"^-\s+(.+?)\s*$") # A wrapped bullet: indented, directly under one. Without this a bullet # that runs past the line width is announced truncated mid-sentence. _CONTINUATION: Final = re.compile(r"^\s+(\S.*?)\s*$") @dataclass(frozen=True, slots=True) class Release: """One released version and the lines describing it.""" version: str pope: str lines: tuple[str, ...] @property def ordinal(self) -> int: """The papal ordinal this release carries.""" return ordinal_for(self.version) @property def pope_entry(self) -> Pope: """The pope this release is named after, from popes.json. Display reads this, never the ``pope`` field parsed off the heading: the name is derived from the version, so a typo in the document cannot make the bot announce the wrong pope into a group. """ return pope_for(self.ordinal) def parse(text: str) -> tuple[Release, ...]: """Return every release in the document, oldest first.""" releases: list[Release] = [] version = pope = "" lines: list[str] = [] open_bullet = False for raw in text.splitlines(): heading = _HEADING.match(raw) if heading is not None: if version: releases.append(Release(version, pope, tuple(lines))) version, pope, lines = heading.group(1), heading.group(2), [] open_bullet = False continue bullet = _BULLET.match(raw) if bullet is not None and version: lines.append(bullet.group(1)) open_bullet = True continue continuation = _CONTINUATION.match(raw) if continuation is not None and open_bullet: lines[-1] = f"{lines[-1]} {continuation.group(1)}" continue open_bullet = False if version: releases.append(Release(version, pope, tuple(lines))) return tuple(sorted(releases, key=lambda release: release.ordinal)) def load(path: Path | None = None) -> tuple[Release, ...]: """Return every release, or nothing if the changelog is not on disk. A missing changelog must not stop the bot: it is documentation that lives outside the package, so an odd install layout should cost an announcement rather than the whole process. """ source = DEFAULT_PATH if path is None else path try: text = source.read_text(encoding="utf-8") except OSError: return () return parse(text) def since(releases: tuple[Release, ...], previous: str) -> tuple[Release, ...]: """Return the releases newer than ``previous``, oldest first.""" try: floor = ordinal_for(previous) except ValueError: return () return tuple(release for release in releases if release.ordinal > floor)