android-watcher 1.0.0__py3-none-any.whl

android_watcher/lock.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import os
+from collections.abc import Iterator
+
+from .models import AlreadyRunning  # single definition lives in models.py
+
+__all__ = ["AlreadyRunning", "run_lock"]
+
+
+@contextlib.contextmanager
+def run_lock(data_dir: str) -> Iterator[None]:
+	"""Acquire an exclusive flock on ``data_dir/run.lock``.
+
+	Raises ``AlreadyRunning`` if the lock is already held by another process.
+	"""
+	os.makedirs(data_dir, exist_ok=True)
+	lock_path = os.path.join(data_dir, "run.lock")
+	fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
+	try:
+		try:
+			fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+		except OSError as exc:
+			raise AlreadyRunning(f"another android-watcher run holds {lock_path}") from exc
+		try:
+			yield
+		finally:
+			fcntl.flock(fd, fcntl.LOCK_UN)
+	finally:
+		os.close(fd)

android_watcher/models.py

@@ -0,0 +1,156 @@
+"""Shared types: dataclasses, type aliases, exceptions, and constants.
+
+Everything here is defined ONCE and imported everywhere else. Keeping the four
+exceptions, ``Check``, ``SignalType``, and ``INTERVAL_DELTA`` in this one module
+gives the package a single source of truth and an acyclic import graph.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Literal
+
+DetectorName = Literal["feed", "android_sitemap", "sitemap", "content"]
+Verdict = Literal["substantive", "cosmetic"]
+ChangeKind = Literal["new", "updated"]
+# How a sitemap source treats reference docs:
+#   keep        - no special handling
+#   drop        - exclude any URL with a "reference" path segment
+#   index_only  - keep only reference index/summary pages (Kotlin-preferred),
+#                 dropping per-symbol class/function pages
+ReferenceMode = Literal["keep", "drop", "index_only"]
+SignalType = Literal["sitemap", "content"]  # snapshots.signal_type
+# android_sitemap + sitemap write "sitemap" (lastmod-confirmed-by-content);
+# content detector writes "content". The feed detector writes NO snapshot
+# (it dedupes per-item via seen_feed_items), so there is no "feed" signal_type.
+
+# Shared schedule-interval mapping: defined ONCE here, imported by the catch-up
+# gate (run.py), the scheduler (schedule.py), and doctor. cron => always due.
+INTERVAL_DELTA = {
+	"hourly": timedelta(hours=1),
+	"daily": timedelta(days=1),
+	"weekly": timedelta(days=7),
+}
+
+
+# Shared exceptions: defined ONCE here, imported by lock/config/fetch/notify so
+# there is exactly one class per error and no circular imports.
+class ConfigError(ValueError):
+	"""Raised on a malformed or contradictory configuration."""
+
+
+class AlreadyRunning(RuntimeError):
+	"""Raised when another android-watcher run already holds the run lock."""
+
+
+class Disallowed(RuntimeError):
+	"""Raised when robots.txt forbids fetching a URL."""
+
+
+class NotifyError(RuntimeError):
+	"""Raised when a Notifier fails to deliver a digest."""
+
+
+@dataclass(frozen=True)
+class Source:
+	id: str
+	name: str
+	category: str
+	detector: DetectorName
+	url: str
+	enabled: bool = True
+	path_prefix: str = ""
+	feed_url: str = ""
+	content_selector: str = ""
+	default_weight: int = 0  # 0 => use category weight
+	# Sitemap-source filters (host-agnostic android_sitemap detector):
+	exclude_prefixes: tuple[str, ...] = ()  # drop URLs under any of these paths
+	require_segment: str = ""  # if set, keep only URLs with a matching path segment
+	# Default index_only: reference docs are filtered to index/summary pages site-
+	# wide (a no-op on sources with no /reference pages). Override per source.
+	reference_mode: ReferenceMode = "index_only"
+
+
+@dataclass
+class Change:
+	source_id: str
+	url: str
+	change_kind: ChangeKind
+	title: str = ""
+	raw_diff: str = ""  # short excerpt / diff text
+	fetched_hash: str = ""  # confirmed content hash
+	detected_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+	id: int | None = None  # set by Store.record_change
+	verdict: Verdict | None = None
+	description: str | None = None  # filled by Triager for substantive
+	group_key: str | None = None  # model-assigned grouping slug; same slug = same group
+	group_summary: str | None = None  # merged one-line summary for the group, or None
+	group_title: str | None = None  # short model headline naming the group, or None
+
+
+@dataclass
+class DigestItem:
+	change: Change
+	score: int
+
+
+@dataclass
+class DigestGroup:
+	key: str
+	title: str
+	summary: str | None
+	category: str
+	source_id: str
+	change_kind: ChangeKind
+	members: list[Change]  # newest-first; len >= 1
+	score: int = 0
+
+	@property
+	def primary_url(self) -> str:
+		return self.members[0].url
+
+	@property
+	def page_count(self) -> int:
+		return len(self.members)
+
+
+@dataclass
+class Digest:
+	groups: list[DigestGroup]  # all groups, ranked (score DESC)
+	max_items: int = 10  # cap on groups shown in the on-channel message
+	tldr: str | None = None
+	ai_unavailable: str | None = None
+	sources_scanned: int = 0
+	pages_watched: int = 0
+	generated_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+	@property
+	def is_empty(self) -> bool:
+		return not self.groups
+
+	def message_groups(self) -> list[DigestGroup]:
+		return self.groups[: self.max_items]
+
+	def carried_groups(self) -> list[DigestGroup]:
+		return self.groups[self.max_items :]
+
+	def change_count(self) -> int:
+		return sum(g.page_count for g in self.groups)
+
+
+@dataclass(frozen=True)
+class Check:
+	name: str  # health-check result; lives here so doctor.py and schedule.py
+	ok: bool  # both import it without a circular import
+	detail: str
+
+
+@dataclass
+class FetchResult:
+	url: str
+	status: int  # real HTTP status; 304 when not_modified
+	text: str  # "" when not_modified
+	etag: str = ""
+	last_modified: str = ""
+	not_modified: bool = False  # True on HTTP 304

android_watcher/notify/__init__.py

@@ -0,0 +1 @@
+from . import email, slack, telegram  # noqa: F401

android_watcher/notify/base.py

@@ -0,0 +1,21 @@
+"""Notifier protocol, re-export of NotifyError, and NOTIFIERS registry."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from android_watcher.config import Config
+from android_watcher.models import Digest, NotifyError  # shared exception defined in models.py
+from android_watcher.registry import Registry
+
+__all__ = ["NotifyError", "Notifier", "NOTIFIERS"]
+
+
+@runtime_checkable
+class Notifier(Protocol):
+	name: str
+
+	def send(self, digest: Digest, config: Config) -> set[int]: ...
+
+
+NOTIFIERS: Registry[Notifier] = Registry("notifier")

android_watcher/notify/email.py

@@ -0,0 +1,52 @@
+"""Email notifier: sends digest via SMTP with TLS enforced (fail closed)."""
+
+from __future__ import annotations
+
+import smtplib
+import ssl
+from email.message import EmailMessage
+
+from android_watcher.config import Config
+from android_watcher.models import Digest
+from android_watcher.notify.base import NOTIFIERS, NotifyError
+from android_watcher.notify.render import render_email
+
+
+@NOTIFIERS.register("email")
+class EmailNotifier:
+	name = "email"
+
+	def send(self, digest: Digest, config: Config) -> set[int]:
+		ec = config.email
+		html, plaintext = render_email(digest)
+
+		msg = EmailMessage()
+		msg["From"] = ec.sender
+		msg["To"] = ec.recipient
+		msg["Subject"] = "android-watcher digest"
+		msg.set_content(plaintext)
+		msg.add_alternative(html, subtype="html")
+
+		context = ssl.create_default_context()
+		try:
+			if ec.smtp_port == 465:
+				with smtplib.SMTP_SSL(ec.smtp_host, ec.smtp_port, context=context) as s:
+					s.login(ec.username, ec.password)
+					s.send_message(msg)
+			else:
+				with smtplib.SMTP(ec.smtp_host, ec.smtp_port) as s:
+					s.ehlo()
+					if not s.has_extn("starttls"):
+						raise NotifyError(
+							f"SMTP server {ec.smtp_host}:{ec.smtp_port} does not advertise "
+							"STARTTLS; refusing to send over plaintext"
+						)
+					s.starttls(context=context)
+					s.ehlo()
+					s.login(ec.username, ec.password)
+					s.send_message(msg)
+		except NotifyError:
+			raise
+		except (smtplib.SMTPException, OSError, ssl.SSLError) as exc:
+			raise NotifyError(f"email send failed: {exc}") from exc
+		return {m.id for g in digest.groups for m in g.members if m.id is not None}

android_watcher/notify/html.py

@@ -0,0 +1,114 @@
+"""Render a Digest into a standalone full-digest HTML page (all groups)."""
+
+from __future__ import annotations
+
+import html as _html
+
+from android_watcher.models import Digest, DigestGroup
+from android_watcher.rank import by_category
+
+_HEAD = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Android Watcher Digest</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@500&display=swap" rel="stylesheet">
+<style>
+:root{--ink:#14171f;--paper:#faf9f5;--muted:#6b7180;--faint:#9aa0ac;--hair:#e7e6df;--signal:#1f9d57;--signal-soft:#e6f4ec;--card:#fff;--display:"Space Grotesk",system-ui,sans-serif;--body:"Inter",system-ui,sans-serif;--mono:"JetBrains Mono",ui-monospace,Menlo,monospace}
+@media(prefers-color-scheme:dark){:root{--ink:#e9e8e2;--paper:#101218;--muted:#9aa0ac;--faint:#6b7180;--hair:#262932;--signal:#3ddc84;--signal-soft:#15271d;--card:#171a22}}
+*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font-family:var(--body);font-size:15px;line-height:1.55;-webkit-font-smoothing:antialiased}
+.wrap{max-width:720px;margin:0 auto;padding:0 20px 72px}
+header.mast{text-align:center;padding:48px 0 28px}
+.mast h1{font-family:var(--display);font-weight:700;font-size:40px;letter-spacing:-.02em;margin:0;line-height:1.05}
+.scan{width:64px;height:2px;margin:22px auto 18px;border-radius:2px;background:linear-gradient(90deg,transparent,var(--signal),transparent)}
+.mast .stats{font-family:var(--mono);font-size:12.5px;color:var(--muted);display:flex;gap:14px;justify-content:center;flex-wrap:wrap}
+.mast .stats b{color:var(--ink);font-weight:600}
+.cat{display:flex;align-items:baseline;gap:12px;margin:38px 0 10px}
+.cat h2{font-family:var(--mono);font-size:12px;letter-spacing:.18em;text-transform:uppercase;color:var(--muted);font-weight:500;margin:0;white-space:nowrap}
+.cat .rule{flex:1;height:1px;background:var(--hair)}.cat .n{font-family:var(--mono);font-size:12px;color:var(--faint)}
+.row{background:var(--card);border:1px solid var(--hair);border-radius:12px;margin:8px 0;padding:16px 18px}
+.titleline{display:flex;align-items:center;gap:10px}.tick{width:7px;height:7px;border-radius:50%;background:var(--signal);flex:none}
+.title{font-family:var(--display);font-weight:600;font-size:17px;letter-spacing:-.01em}
+.src{font-family:var(--mono);font-size:11px;color:var(--faint);margin:7px 0 0 17px}
+.point{margin:9px 0 0 17px;color:var(--ink)}
+.lbl{font-family:var(--mono);font-size:10.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--faint);margin:13px 0 6px 17px}
+ol.sources{margin:0 0 0 17px;padding-left:22px}ol.sources li{margin:4px 0}
+.src-one{margin:11px 0 0 17px;font-size:14px}
+a{color:var(--signal)}a:hover{text-decoration:underline}.sources a,.src-one a{text-decoration:underline}
+.banner{margin:0 0 24px;padding:12px 18px;border:1px solid #e6a817;border-radius:10px;background:#fffbee;color:#7a4f00;font-family:var(--mono);font-size:12.5px;text-align:center}
+@media(prefers-color-scheme:dark){.banner{border-color:#7a4f00;background:#1e1600;color:#f5c842}}
+.coverage{margin-top:44px;padding:24px;border:1px solid var(--hair);border-radius:14px;background:var(--card);display:flex;text-align:center}
+.coverage .cell{flex:1;padding:4px 8px}.coverage .cell+.cell{border-left:1px solid var(--hair)}
+.coverage .num{font-family:var(--display);font-weight:700;font-size:34px;letter-spacing:-.02em;color:var(--signal);line-height:1}
+.coverage .lbl{font-family:var(--mono);font-size:11px;letter-spacing:.16em;text-transform:uppercase;color:var(--muted);margin-top:8px}
+footer{text-align:center;margin-top:22px;font-family:var(--mono);font-size:11px;letter-spacing:.12em;text-transform:uppercase;color:var(--faint)}
+</style></head><body><div class="wrap">"""
+
+_FOOT = "</div></body></html>"
+
+
+def _esc(s: str) -> str:
+	return _html.escape(s or "")
+
+
+def clean_label(title: str) -> str:
+	"""Display form of a page title: drop a trailing ' | Site' / ' — Site' suffix
+	so link text reads as the page name, not 'Page | Android Open Source Project'."""
+	if not title:
+		return ""
+	for sep in (" | ", " — ", " – ", " · "):
+		if sep in title:
+			return title.split(sep)[0].strip()
+	return title.strip()
+
+
+def _link(m) -> str:
+	label = clean_label(m.title) or m.url
+	return f'<a href="{_esc(m.url)}">{_esc(label)}</a>'
+
+
+def _row(g: DigestGroup) -> str:
+	parts = [
+		'<div class="row">',
+		f'<div class="titleline"><span class="tick"></span>'
+		f'<span class="title">{_esc(clean_label(g.title))}</span></div>',
+		f'<div class="src">{_esc(g.source_id)} · {_esc(g.change_kind)}</div>',
+	]
+	if g.summary:
+		parts.append(f'<p class="point">{_esc(g.summary)}</p>')
+	if g.page_count > 1:
+		items = "".join(f"<li>{_link(m)}</li>" for m in g.members)
+		parts.append(f'<div class="lbl">Sources</div><ol class="sources" type="i">{items}</ol>')
+	else:
+		parts.append(f'<div class="src-one">Source: {_link(g.members[0])}</div>')
+	parts.append("</div>")
+	return "".join(parts)
+
+
+def render_html(digest: Digest) -> str:
+	date = digest.generated_at.strftime("%d %b %Y")
+	parts = [_HEAD]
+	parts.append(
+		'<header class="mast"><h1>Android Watcher Digest</h1><div class="scan"></div>'
+		f'<div class="stats"><span><b>{date}</b></span>'
+		f"<span><b>{len(digest.groups)}</b> groups</span>"
+		f"<span><b>{digest.change_count()}</b> changes</span></div></header>"
+	)
+	if digest.ai_unavailable:
+		parts.append(f'<div class="banner">AI unavailable: {_esc(digest.ai_unavailable)}</div>')
+	for _cid, label, groups in by_category(digest.groups):
+		parts.append(
+			f'<div class="cat"><h2>{_esc(label)}</h2><span class="rule"></span>'
+			f'<span class="n">{len(groups)}</span></div>'
+		)
+		parts.extend(_row(g) for g in groups)
+	parts.append(
+		'<div class="coverage">'
+		f'<div class="cell"><div class="num">{digest.sources_scanned}</div>'
+		'<div class="lbl">sources scanned</div></div>'
+		f'<div class="cell"><div class="num">{digest.pages_watched:,}</div>'
+		'<div class="lbl">pages watched</div></div></div>'
+		"<footer>Android Watcher Digest</footer>"
+	)
+	parts.append(_FOOT)
+	return "".join(parts)

android_watcher/notify/render.py

@@ -0,0 +1,239 @@
+"""Render a Digest into email (HTML + plaintext), Telegram, and Slack blocks."""
+
+from __future__ import annotations
+
+import html as _html
+
+from android_watcher.models import Digest, DigestGroup
+from android_watcher.notify.html import clean_label, render_html
+from android_watcher.rank import by_category
+
+
+def _banner_text(digest: Digest) -> str | None:
+	return f"AI unavailable: {digest.ai_unavailable}" if digest.ai_unavailable else None
+
+
+def _scan_footer(digest: Digest) -> str | None:
+	"""Scan-scope line shown at the foot of every delivered digest, or None."""
+	if not digest.sources_scanned:
+		return None
+	return f"Scanned {digest.sources_scanned} Sources · Watching {digest.pages_watched:,} Pages"
+
+
+def _points_plaintext(digest: Digest) -> list[str]:
+	lines: list[str] = []
+	for _cid, label, groups in by_category(digest.groups):
+		lines.append(f"## {label}")
+		for g in groups:
+			pages = f" ({g.page_count} pages)" if g.page_count > 1 else ""
+			lines.append(f"- {g.title}{pages} [{g.source_id}/{g.change_kind}]")
+			if g.summary:
+				lines.append(f"    {g.summary}")
+	return lines
+
+
+def render_email(digest: Digest) -> tuple[str, str]:
+	html = render_html(digest)
+	p_lines: list[str] = []
+	banner = _banner_text(digest)
+	if banner:
+		p_lines.append(banner)
+	p_lines.append("Android Watcher Digest")
+	if digest.is_empty:
+		p_lines.append("Nothing notable changed.")
+	else:
+		p_lines.extend(_points_plaintext(digest))
+	footer = _scan_footer(digest)
+	if footer:
+		p_lines.append(footer)
+	return html, "\n".join(p_lines)
+
+
+_TELEGRAM_LIMIT = 4096
+
+
+def render_telegram(digest: Digest) -> str:
+	"""Render a digest as an HTML-formatted Telegram message.
+
+	Uses parse_mode=HTML. User/content text is html-escaped. If the assembled
+	message would exceed Telegram's 4096-character limit, groups are dropped
+	(trailing ones first) and a "…(N more)" note is appended.
+	"""
+	parts: list[str] = ["<b>Android Watcher Digest</b>"]
+	banner = _banner_text(digest)
+	if banner:
+		parts.insert(0, f"<b>{_html.escape(banner)}</b>")
+	scan = _scan_footer(digest)
+	scan_line = f"<i>{_html.escape(scan)}</i>" if scan else None
+	if digest.is_empty:
+		parts.append("Nothing notable changed.")
+		if scan_line:
+			parts.append(scan_line)
+		return "\n".join(parts)
+
+	item_lines: list[str] = []
+	for g in digest.message_groups():
+		pages = f" ({g.page_count} pages)" if g.page_count > 1 else ""
+		label = _html.escape(g.title)
+		src_tag = f"[{_html.escape(g.source_id)}/{_html.escape(g.change_kind)}]{pages}"
+		line = f'<a href="{_html.escape(g.primary_url)}">{label}</a> {src_tag}'
+		if g.summary:
+			line += f"\n{_html.escape(g.summary)}"
+		item_lines.append(line)
+
+	carried = digest.carried_groups()
+	footer_lines = [f"+{len(carried)} more groups"] if carried else []
+	header = "\n".join(parts)
+	footer = "\n".join(footer_lines)
+
+	def _assemble(items: list[str], dropped: int) -> str:
+		sections = [header, *items]
+		if dropped:
+			sections.append(f"…({dropped} more)")
+		if footer:
+			sections.append(footer)
+		if scan_line:
+			sections.append(scan_line)
+		return "\n".join(sections)
+
+	msg = _assemble(item_lines, 0)
+	if len(msg) <= _TELEGRAM_LIMIT:
+		return msg
+
+	# Drop groups from the end until it fits.
+	dropped = 0
+	while item_lines and len(_assemble(item_lines, dropped)) > _TELEGRAM_LIMIT:
+		item_lines.pop()
+		dropped += 1
+
+	return _assemble(item_lines, dropped)
+
+
+_MEMBER_LINK_CAP = 12  # most member links to inline before summarizing the rest
+
+
+def _slack_link_label(text: str) -> str:
+	"""Clean a page title for display, then escape what would break a Slack
+	`<url|label>` link: a raw `|` ends the label, and `& < >` need escaping."""
+	label = clean_label(text)
+	return label.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace("|", "/")
+
+
+_ROMAN = [
+	(1000, "m"),
+	(900, "cm"),
+	(500, "d"),
+	(400, "cd"),
+	(100, "c"),
+	(90, "xc"),
+	(50, "l"),
+	(40, "xl"),
+	(10, "x"),
+	(9, "ix"),
+	(5, "v"),
+	(4, "iv"),
+	(1, "i"),
+]
+
+
+def _roman(n: int) -> str:
+	"""Lowercase roman numeral for the source list (i, ii, iii, …)."""
+	out: list[str] = []
+	for value, sym in _ROMAN:
+		while n >= value:
+			out.append(sym)
+			n -= value
+	return "".join(out)
+
+
+def _group_section(g: DigestGroup, number: int | None = None) -> dict:
+	"""One section per group: bold 'Title:' (numbered when its category holds
+	more than one group), an optional normal-weight summary, then the source
+	link(s). A single-source group shows '*Source:* <link>'; a multi-source group
+	shows '*Sources:*' then a lowercase roman-numeral list (capped). No buttons:
+	one button could never represent a group's N urls."""
+	clean = clean_label(g.title)
+	title = clean if clean.endswith(":") else f"{clean}:"
+	head = f"{number}. {title}" if number else title
+	text = f"*{head}*"
+	if g.summary:
+		text += f"\n{g.summary}"
+	if g.page_count == 1:
+		m = g.members[0]
+		text += f"\n\n*Source:* <{m.url}|{_slack_link_label(m.title or m.url)}>"
+	else:
+		shown = g.members[:_MEMBER_LINK_CAP]
+		rows = "\n".join(
+			f"{_roman(i)}. <{m.url}|{_slack_link_label(m.title or m.url)}>"
+			for i, m in enumerate(shown, 1)
+		)
+		text += f"\n\n*Sources:*\n{rows}"
+		if g.page_count > _MEMBER_LINK_CAP:
+			text += f"\n…+{g.page_count - _MEMBER_LINK_CAP} more"
+	return {"type": "section", "text": {"type": "mrkdwn", "text": text}}
+
+
+def render_slack(digest: Digest, *, thread_page: bool = False) -> dict:
+	"""Render the capped Slack message. ``thread_page`` is True when the notifier
+	will also upload the full-digest HTML page into a thread; the footer then
+	mentions it. False omits the thread reference."""
+	blocks: list[dict] = []
+	banner = _banner_text(digest)
+	if banner:
+		blocks.append({"type": "section", "text": {"type": "mrkdwn", "text": f"*{banner}*"}})
+	date = digest.generated_at.strftime("%d %b %Y")
+	blocks.append(
+		{
+			"type": "header",
+			"text": {
+				"type": "plain_text",
+				"text": f"Android Watcher Digest · {date}",
+				"emoji": True,
+			},
+		}
+	)
+	if digest.is_empty:
+		blocks.append(
+			{"type": "section", "text": {"type": "mrkdwn", "text": "Nothing notable changed."}}
+		)
+		footer = _scan_footer(digest)
+		if footer:
+			blocks.append({"type": "context", "elements": [{"type": "mrkdwn", "text": footer}]})
+		return {"blocks": blocks}
+
+	shown = digest.message_groups()
+	# A native divider opens each category (Slack has no thick/thin rule, so the
+	# divider is the category separator and there is no inner rule). Groups in a
+	# category with more than one group are numbered 1., 2., …
+	for _cid, label, groups in by_category(shown):
+		blocks.append({"type": "divider"})
+		blocks.append(
+			{"type": "section", "text": {"type": "mrkdwn", "text": f"*{label}  ·  {len(groups)}*"}}
+		)
+		numbered = len(groups) > 1
+		for i, g in enumerate(groups, 1):
+			blocks.append(_group_section(g, i if numbered else None))
+
+	carried = digest.carried_groups()
+	footer_bits: list[str] = []
+	if thread_page:
+		footer_bits.append(
+			f"Full digest - *{len(digest.groups)} groups"
+			f" · {digest.change_count()} changes* - Attached in :thread:"
+		)
+	if carried:
+		names = ", ".join(g.title for g in carried[:3])
+		footer_bits.append(f"+{len(carried)} more groups: {names}")
+	scan = _scan_footer(digest)
+	tail: list[dict] = []
+	if footer_bits:
+		tail.append(
+			{"type": "context", "elements": [{"type": "mrkdwn", "text": "   ".join(footer_bits)}]}
+		)
+	if scan:
+		tail.append({"type": "context", "elements": [{"type": "mrkdwn", "text": scan}]})
+	# Closing divider before the footer region (only when there is a footer).
+	if tail:
+		blocks.append({"type": "divider"})
+		blocks.extend(tail)
+	return {"blocks": blocks}