repomatic 7.7.0__tar.gz → 7.9.0__tar.gz

{repomatic-7.7.0 → repomatic-7.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repomatic
-Version: 7.7.0
+Version: 7.9.0
 Summary: 🏭 Automate repository maintenance, releases, and CI/CD workflows
 Keywords: changelog-formatter,dependabot-alternative,github-actions,github-labels,github-workflow,gitignore,mailmap,mypy,nuitka,python-automation,release-automation,repository-automation,repository-management,reusable-workflows,software-factory,sphinx-doc,typo,uv,workflow-reusable
 Author: Kevin Deldycke
@@ -59,7 +59,7 @@ Requires-Dist: wcmatch>=10
 Requires-Python: >=3.10
 Project-URL: Changelog, https://github.com/kdeldycke/repomatic/blob/main/changelog.md
 Project-URL: Documentation, https://kdeldycke.github.io/repomatic
-Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.7.0
+Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.9.0
 Project-URL: Funding, https://github.com/sponsors/kdeldycke
 Project-URL: Homepage, https://github.com/kdeldycke/repomatic
 Project-URL: Issues, https://github.com/kdeldycke/repomatic/issues
@@ -67,14 +67,13 @@ Project-URL: Repository, https://github.com/kdeldycke/repomatic
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="docs/assets/logo-banner.svg" alt="repomatic">
+  <img src="https://raw.githubusercontent.com/kdeldycke/repomatic/main/docs/assets/logo-banner.svg" alt="repomatic">
 </p>
 
 [![Last release](https://img.shields.io/pypi/v/repomatic.svg)](https://pypi.org/project/repomatic/)
 [![Python versions](https://img.shields.io/pypi/pyversions/repomatic.svg)](https://pypi.org/project/repomatic/)
 [![Downloads](https://static.pepy.tech/badge/repomatic/month)](https://pepy.tech/projects/repomatic)
 [![Unittests status](https://img.shields.io/github/actions/workflow/status/kdeldycke/repomatic/tests.yaml?branch=main&label=%F0%9F%94%AC%20Tests)](https://github.com/kdeldycke/repomatic/actions/workflows/tests.yaml?query=branch%3Amain)
-[![Coverage status](https://codecov.io/gh/kdeldycke/repomatic/branch/main/graph/badge.svg)](https://app.codecov.io/gh/kdeldycke/repomatic)
 [![Documentation status](https://img.shields.io/github/actions/workflow/status/kdeldycke/repomatic/docs.yaml?branch=main&label=%F0%9F%93%9A%20Docs)](https://github.com/kdeldycke/repomatic/actions/workflows/docs.yaml?query=branch%3Amain)
 
 A Python CLI and `pyproject.toml` configuration that let you **release Python packages multiple times a day with only 2-clicks**. Designed for `uv`-based Python projects, but usable for other projects too. Every step is a CLI command: reusable GitHub Actions workflows are only the trigger, so the same automation runs on your machine.
@@ -160,8 +159,11 @@ Check these projects to get real-life examples of usage and inspiration:
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/meta-package-manager?label=%E2%AD%90&style=flat-square) [Meta Package Manager](https://github.com/kdeldycke/meta-package-manager) - A unifying CLI for multiple package managers.
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/mail-deduplicate?label=%E2%AD%90&style=flat-square) [Mail Deduplicate](https://github.com/kdeldycke/mail-deduplicate) - A CLI to deduplicate similar emails.
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/dotfiles?label=%E2%AD%90&style=flat-square) [dotfiles](https://github.com/kdeldycke/dotfiles) - macOS dotfiles for Python developers.
-- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/click-extra?label=%E2%AD%90&style=flat-square) [Click Extra](https://github.com/kdeldycke/click-extra) - Extra colorization and configuration loading for Click.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/click-extra?label=%E2%AD%90&style=flat-square) [Click Extra](https://github.com/kdeldycke/click-extra) - Drop-in replacement for Click to make user-friendly and colorful CLI.
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/repomatic?label=%E2%AD%90&style=flat-square) [repomatic](https://github.com/kdeldycke/repomatic) - Itself. Eat your own dog-food.
-- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/extra-platforms?label=%E2%AD%90&style=flat-square) [Extra Platforms](https://github.com/kdeldycke/extra-platforms) - Detect platforms and group them by family.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/plumage?label=%E2%AD%90&style=flat-square) [Plumage](https://github.com/kdeldycke/plumage) - Clean and tidy theme for Pelican, the static site generator.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/kevin-deldycke-blog?label=%E2%AD%90&style=flat-square) [Kevin Deldycke's blog](https://github.com/kdeldycke/kevin-deldycke-blog) - My personal blog, based on Pelican.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/extra-platforms?label=%E2%AD%90&style=flat-square) [Extra Platforms](https://github.com/kdeldycke/extra-platforms) - Detect architectures, platforms, shells, terminals, CI systems and agents, grouped by family.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/kdeldycke?label=%E2%AD%90&style=flat-square) [GitHub profile](https://github.com/kdeldycke/kdeldycke) - My GitHub profile page and short bio.
 
 Send a PR to add your project if you use repomatic.

{repomatic-7.7.0 → repomatic-7.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["uv-build>=0.8"]
 
 [project]
 name = "repomatic"
-version = "7.7.0"
+version = "7.9.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -92,7 +92,7 @@ email = "kevin@deldycke.com"
 [project.urls]
 Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 Documentation = "https://kdeldycke.github.io/repomatic"
-Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.7.0"
+Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.9.0"
 Funding = "https://github.com/sponsors/kdeldycke"
 Homepage = "https://github.com/kdeldycke/repomatic"
 Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -146,7 +146,7 @@ module-root = ""
 [tool.nuitka]
 copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed under GPL-2.0-or-later license."
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
-file-version = "7.7.0"
+file-version = "7.9.0"
 include-data-dir = [
     "repomatic/data/awesome_template=repomatic/data/awesome_template",
     "repomatic/data/skills=repomatic/data/skills",
@@ -156,7 +156,7 @@ include-package-data = ["click_extra"]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.7.0"
+product-version = "7.9.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -246,10 +246,11 @@ branch = true
 source = ["repomatic"]
 
 [tool.coverage.report]
+fail_under = 80
 precision = 2
 
 [tool.bumpversion]
-current_version = "7.7.0"
+current_version = "7.9.0"
 parse = '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.dev(?P<dev>\d+))?'
 serialize = [
     "{major}.{minor}.{patch}.dev{dev}",

{repomatic-7.7.0 → repomatic-7.9.0}/pyproject.toml.orig

@@ -12,7 +12,7 @@ requires = [ "uv-build>=0.8" ]
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "repomatic"
-version = "7.7.0"
+version = "7.9.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -145,7 +145,7 @@ dependencies = [
 ]
 urls.Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 urls.Documentation = "https://kdeldycke.github.io/repomatic"
-urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.7.0"
+urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.9.0"
 urls.Funding = "https://github.com/sponsors/kdeldycke"
 urls.Homepage = "https://github.com/kdeldycke/repomatic"
 urls.Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -250,7 +250,7 @@ copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed u
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 # Numeric only: Nuitka rejects PEP 440 .devN suffixes. Kept in sync with the
 # package version by the dedicated [tool.bumpversion] rule that strips the suffix.
-file-version = "7.7.0"
+file-version = "7.9.0"
 include-data-dir = [
   "repomatic/data/awesome_template=repomatic/data/awesome_template",
   "repomatic/data/skills=repomatic/data/skills",
@@ -269,7 +269,7 @@ include-package-data = [ "click_extra" ]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.7.0"
+product-version = "7.9.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -395,10 +395,19 @@ xfail_strict = true
 # https://coverage.readthedocs.io/en/latest/config.html
 run.branch = true
 run.source = [ "repomatic" ]
+# Coverage ratchet: the suite fails below this. The matrix floor sits near
+# 81.6%, since the only cell-dependent tests (tests/test_sphinx_crossrefs.py)
+# run on Linux + Python 3.14 alone and push that cell *up*; the package holds
+# four platform-conditional lines total, so the OS spread is noise. ~1.6 points
+# of margin absorbs that without waving a real regression through.
+#
+# The `once-tests` workflow job overrides this to 0, covering ~22% on its own
+# by design. A focused local run trips it too, so pair those with `--no-cov`.
+report.fail_under = 80
 report.precision = 2
 
 [tool.bumpversion]
-current_version = "7.7.0"
+current_version = "7.9.0"
 # Parse versions with an optional .devN suffix (PEP 440).
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.dev(?P<dev>\\d+))?"
 serialize = [

{repomatic-7.7.0 → repomatic-7.9.0}/readme.md

@@ -1,12 +1,11 @@
 <p align="center">
-  <img src="docs/assets/logo-banner.svg" alt="repomatic">
+  <img src="https://raw.githubusercontent.com/kdeldycke/repomatic/main/docs/assets/logo-banner.svg" alt="repomatic">
 </p>
 
 [![Last release](https://img.shields.io/pypi/v/repomatic.svg)](https://pypi.org/project/repomatic/)
 [![Python versions](https://img.shields.io/pypi/pyversions/repomatic.svg)](https://pypi.org/project/repomatic/)
 [![Downloads](https://static.pepy.tech/badge/repomatic/month)](https://pepy.tech/projects/repomatic)
 [![Unittests status](https://img.shields.io/github/actions/workflow/status/kdeldycke/repomatic/tests.yaml?branch=main&label=%F0%9F%94%AC%20Tests)](https://github.com/kdeldycke/repomatic/actions/workflows/tests.yaml?query=branch%3Amain)
-[![Coverage status](https://codecov.io/gh/kdeldycke/repomatic/branch/main/graph/badge.svg)](https://app.codecov.io/gh/kdeldycke/repomatic)
 [![Documentation status](https://img.shields.io/github/actions/workflow/status/kdeldycke/repomatic/docs.yaml?branch=main&label=%F0%9F%93%9A%20Docs)](https://github.com/kdeldycke/repomatic/actions/workflows/docs.yaml?query=branch%3Amain)
 
 A Python CLI and `pyproject.toml` configuration that let you **release Python packages multiple times a day with only 2-clicks**. Designed for `uv`-based Python projects, but usable for other projects too. Every step is a CLI command: reusable GitHub Actions workflows are only the trigger, so the same automation runs on your machine.
@@ -92,8 +91,11 @@ Check these projects to get real-life examples of usage and inspiration:
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/meta-package-manager?label=%E2%AD%90&style=flat-square) [Meta Package Manager](https://github.com/kdeldycke/meta-package-manager) - A unifying CLI for multiple package managers.
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/mail-deduplicate?label=%E2%AD%90&style=flat-square) [Mail Deduplicate](https://github.com/kdeldycke/mail-deduplicate) - A CLI to deduplicate similar emails.
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/dotfiles?label=%E2%AD%90&style=flat-square) [dotfiles](https://github.com/kdeldycke/dotfiles) - macOS dotfiles for Python developers.
-- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/click-extra?label=%E2%AD%90&style=flat-square) [Click Extra](https://github.com/kdeldycke/click-extra) - Extra colorization and configuration loading for Click.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/click-extra?label=%E2%AD%90&style=flat-square) [Click Extra](https://github.com/kdeldycke/click-extra) - Drop-in replacement for Click to make user-friendly and colorful CLI.
 - ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/repomatic?label=%E2%AD%90&style=flat-square) [repomatic](https://github.com/kdeldycke/repomatic) - Itself. Eat your own dog-food.
-- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/extra-platforms?label=%E2%AD%90&style=flat-square) [Extra Platforms](https://github.com/kdeldycke/extra-platforms) - Detect platforms and group them by family.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/plumage?label=%E2%AD%90&style=flat-square) [Plumage](https://github.com/kdeldycke/plumage) - Clean and tidy theme for Pelican, the static site generator.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/kevin-deldycke-blog?label=%E2%AD%90&style=flat-square) [Kevin Deldycke's blog](https://github.com/kdeldycke/kevin-deldycke-blog) - My personal blog, based on Pelican.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/extra-platforms?label=%E2%AD%90&style=flat-square) [Extra Platforms](https://github.com/kdeldycke/extra-platforms) - Detect architectures, platforms, shells, terminals, CI systems and agents, grouped by family.
+- ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/kdeldycke?label=%E2%AD%90&style=flat-square) [GitHub profile](https://github.com/kdeldycke/kdeldycke) - My GitHub profile page and short bio.
 
 Send a PR to add your project if you use repomatic.

{repomatic-7.7.0 → repomatic-7.9.0}/repomatic/__init__.py

@@ -17,5 +17,5 @@
 
 from __future__ import annotations
 
-__version__ = "7.7.0"
-__git_tag_sha__ = "2c6e58c0d2ec44e627868095eb4c22b98683c463"
+__version__ = "7.9.0"
+__git_tag_sha__ = "292c4e8438249adeb269808d485409c9b56b49bd"

repomatic-7.9.0/repomatic/attestation.py

@@ -0,0 +1,189 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+"""Naming and packing of the sigstore bundles attached to a release.
+
+`actions/attest` writes every bundle to the same `attestation.json` basename,
+whatever it signed, so each release job has to rename its own before the files
+land in one directory. Three of them did, three different ways: the compiled
+binaries appended the suffix to the full filename, the man-page tarball dropped
+its `.tar.gz` first, and the consumer-declared extra assets were named after the
+*job* rather than any file. A release page therefore carried
+`repomatic-manpages.attestation.json` next to `repomatic-manpages.tar.gz`, and
+`repomatic-extra-assets.attestation.json` next to `repomatic-claude-plugin.zip`.
+
+This module holds the one rule instead: a bundle is named after the artifact it
+attests. The subject list is read back out of the bundle rather than passed in,
+so the name is derived from what was actually signed and no caller can spell it
+differently. See {func}`bundle_filename` for the multi-subject case.
+
+```{note}
+The signing itself stays in `actions/attest`: it needs the job's OIDC token, so
+it cannot move here. This module runs immediately after it, in the same job.
+```
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import shutil
+from pathlib import Path
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import Final
+
+ATTESTATION_SUFFIX: Final[str] = ".attestation.json"
+"""Extension carried by every attestation bundle attached to a release.
+
+Not `.sigstore.json` (the ecosystem's own convention) because these files have
+been published under this name since the first attested release, and a release
+asset name is part of the surface users script against.
+"""
+
+
+def bundle_subjects(bundle_path: Path) -> tuple[str, ...]:
+    """Filenames of the artifacts a sigstore bundle attests.
+
+    A bundle wraps a DSSE envelope whose base64 payload is an in-toto
+    Statement, and that statement's `subject` array names every file signed in
+    the same call. One entry for a single `subject-path`, several when
+    `actions/attest` was handed a glob: "If multiple subjects are being attested
+    at the same time, a single attestation will be created with references to
+    each of the supplied subjects."
+
+    :param bundle_path: The bundle `actions/attest` wrote.
+    :return: Subject filenames, in the order the statement lists them.
+    :raises ValueError: If the file is not a bundle carrying a readable
+        in-toto statement, or names a subject that is not a bare filename.
+    """
+    try:
+        bundle = json.loads(bundle_path.read_text(encoding="UTF-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{bundle_path} is not valid JSON: {exc}") from exc
+
+    payload = (bundle.get("dsseEnvelope") or {}).get("payload")
+    if not payload:
+        raise ValueError(
+            f"{bundle_path} carries no DSSE envelope payload: not an "
+            "attestation bundle."
+        )
+    # A payload that is not a base64 string lands in the same basket as one
+    # that is unreadable, so callers only ever catch ValueError here.
+    try:
+        statement = json.loads(base64.b64decode(payload, validate=True))
+    except (
+        TypeError,
+        binascii.Error,
+        UnicodeDecodeError,
+        json.JSONDecodeError,
+    ) as exc:
+        raise ValueError(f"{bundle_path} has an unreadable payload: {exc}") from exc
+
+    subjects = statement.get("subject")
+    if not isinstance(subjects, list) or not subjects:
+        raise ValueError(f"{bundle_path} attests no subject.")
+
+    names = []
+    for subject in subjects:
+        name = subject.get("name") if isinstance(subject, dict) else None
+        if not isinstance(name, str) or not name:
+            raise ValueError(f"{bundle_path} has a subject with no name.")
+        # A subject name is a bare filename everywhere the release lane
+        # produces one. Reject a path so the join in pack_attestation below
+        # cannot be walked out of the asset directory.
+        if Path(name).name != name:
+            raise ValueError(
+                f"{bundle_path} names subject {name!r}, which is not a bare filename."
+            )
+        names.append(name)
+    return tuple(names)
+
+
+def bundle_filename(subjects: Sequence[str], set_name: str | None = None) -> str:
+    """Name a bundle after the artifact it attests.
+
+    A single subject gives the bundle its own name, suffix appended to the
+    whole filename so the two sort together on a release page listing assets
+    alphabetically (`papaya.tar.gz`, then `papaya.tar.gz.attestation.json`).
+
+    Several subjects have no such name to borrow, since one bundle covers them
+    all, so *set_name* is required and should describe the set rather than any
+    member of it. That case only arises when a job hands `actions/attest` a
+    glob.
+
+    :param subjects: Subject filenames, from {func}`bundle_subjects`.
+    :param set_name: Stem to use when *subjects* holds more than one entry.
+    :return: The bundle's filename.
+    :raises ValueError: If *subjects* is empty, or holds several entries with
+        no *set_name* to fall back on.
+    """
+    if not subjects:
+        raise ValueError("Cannot name a bundle that attests no subject.")
+    if len(subjects) == 1:
+        return f"{subjects[0]}{ATTESTATION_SUFFIX}"
+    if not set_name:
+        raise ValueError(
+            f"Bundle attests {len(subjects)} subjects "
+            f"({', '.join(sorted(subjects))}), so it cannot be named after any "
+            "one of them: pass --name to name the set."
+        )
+    return f"{set_name}{ATTESTATION_SUFFIX}"
+
+
+def pack_attestation(
+    bundle_path: Path,
+    asset_dir: Path,
+    set_name: str | None = None,
+) -> list[Path]:
+    """Name a bundle after its subject and print what to upload with it.
+
+    Copies *bundle_path* into *asset_dir* under the name
+    {func}`bundle_filename` derives, then returns that bundle alongside every
+    artifact it attests, which is exactly the file list the release upload step
+    has to attach for the provenance to be verifiable offline.
+
+    Every subject must already sit in *asset_dir*: a bundle naming a file that
+    is not there means the job attested a different tree than the one it is
+    about to upload, which would publish an asset whose sidecar covers
+    something else. Immutable releases make that unfixable after the fact, so
+    it fails here instead.
+
+    Idempotent: re-running copies the same bytes over the same name.
+
+    :param bundle_path: The bundle `actions/attest` wrote.
+    :param asset_dir: Directory holding the attested artifacts.
+    :param set_name: Stem for the multi-subject case, see
+        {func}`bundle_filename`.
+    :return: Sorted paths to upload, the renamed bundle included.
+    :raises ValueError: If a subject is missing from *asset_dir*.
+    """
+    subjects = bundle_subjects(bundle_path)
+    assets = [asset_dir / name for name in subjects]
+
+    missing = [path.name for path in assets if not path.is_file()]
+    if missing:
+        raise ValueError(
+            f"{bundle_path} attests {', '.join(sorted(missing))}, missing from "
+            f"{asset_dir}."
+        )
+
+    target = asset_dir / bundle_filename(subjects, set_name)
+    shutil.copy2(bundle_path, target)
+    return sorted({*assets, target})

{repomatic-7.7.0 → repomatic-7.9.0}/repomatic/changelog.py

@@ -733,6 +733,64 @@ class Changelog:
         return True
 
 
+def _load_pypi_releases(
+    package: str | None, history: Sequence[str], *, force_refresh: bool = False
+) -> dict[str, PyPIRelease]:
+    """Load a package's PyPI releases, merged with its former names.
+
+    A renamed project keeps its old releases under the old name, so the
+    changelog's early versions resolve only through
+    `[tool.repomatic] pypi.package-history`. The current package wins on
+    version collisions.
+
+    :param package: Current PyPI package name; empty or `None` skips PyPI.
+    :param history: Former package names, oldest-first.
+    :param force_refresh: Ignore cached responses and re-fetch.
+    :return: Dict mapping version strings to {class}`PyPIRelease` tuples.
+    """
+    releases: dict[str, PyPIRelease] = {}
+    if package:
+        releases = get_pypi_release_dates(package, force_refresh=force_refresh)
+    for former_package in history:
+        former_data = get_pypi_release_dates(
+            former_package, force_refresh=force_refresh
+        )
+        if former_data:
+            logging.info(
+                f"Using PyPI history for {former_package!r}"
+                f" ({len(former_data)} releases found)."
+            )
+        for version, release in former_data.items():
+            releases.setdefault(version, release)
+    return releases
+
+
+def _is_platform_gap(
+    parsed: Version,
+    on_platform: bool,
+    platform_known: bool,
+    first_version: Version | None,
+) -> bool:
+    """Whether *parsed* is missing from a platform it should appear on.
+
+    A gap is an absence *after* the platform's first release: versions
+    predating it were never expected there, so they are not warned about.
+
+    :param parsed: The version under test.
+    :param on_platform: Whether the lookup found it on the platform.
+    :param platform_known: Whether the platform is addressable at all (a
+        package name for PyPI, a repository URL for GitHub).
+    :param first_version: Earliest version seen on that platform.
+    :return: `True` when the version is a genuine gap.
+    """
+    return (
+        not on_platform
+        and platform_known
+        and first_version is not None
+        and parsed >= first_version
+    )
+
+
 def _platform_admonition(
     template: str, version: str, verb: str, platforms: Sequence[str]
 ) -> str:
@@ -985,33 +1043,20 @@ def lint_changelog_dates(
     if package is None:
         package = get_project_name()
 
-    # Fetch all PyPI release dates in a single API call.
-    pypi_data: dict[str, PyPIRelease] = {}
-    if package:
-        pypi_data = get_pypi_release_dates(package)
-        if pypi_data:
-            logging.info(
-                f"Using PyPI as reference for {package!r}"
-                f" ({len(pypi_data)} releases found)."
-            )
-        else:
-            logging.info(
-                f"Package {package!r} not found on PyPI, falling back to git tags."
-            )
-    else:
+    # Fetch all PyPI release dates in a single API call, merged with the
+    # releases of any former package name (for renamed projects).
+    pypi_data = _load_pypi_releases(package, pypi_package_history)
+    if not package:
         logging.info("No package name detected, falling back to git tags.")
-
-    # Merge releases from former package names (for renamed projects).
-    for former_package in pypi_package_history:
-        former_data = get_pypi_release_dates(former_package)
-        if former_data:
-            logging.info(
-                f"Using PyPI history for {former_package!r}"
-                f" ({len(former_data)} releases found)."
-            )
-        # Current package wins on version collisions.
-        for v, rel in former_data.items():
-            pypi_data.setdefault(v, rel)
+    elif pypi_data:
+        logging.info(
+            f"Using PyPI as reference for {package!r}"
+            f" ({len(pypi_data)} releases found)."
+        )
+    else:
+        logging.info(
+            f"Package {package!r} not found on PyPI, falling back to git tags."
+        )
 
     use_pypi = bool(pypi_data)
     has_mismatch = False
@@ -1051,6 +1096,98 @@ def lint_changelog_dates(
         first_github_version = min(Version(v) for v in github_releases)
         logging.info(f"First GitHub version: {first_github_version}")
 
+    def retracted_versions() -> set[str]:
+        """Versions whose section claims availability the lookups now deny.
+
+        Reads the enclosing scope on every call, so re-running it after a
+        forced refresh answers against the fresh data. An available platform
+        is rendered as a markdown link and a missing one as a bare label, so
+        the `[` prefix is what separates a claim of presence from one of
+        absence.
+        """
+        found = set()
+        for candidate, _candidate_date in releases:
+            existing = changelog.decompose_version(candidate).availability_admonition
+            parsed_candidate = Version(candidate)
+            drops_pypi = (
+                _is_platform_gap(
+                    parsed_candidate,
+                    candidate in pypi_data,
+                    bool(package),
+                    first_pypi_version,
+                )
+                and f"[{PYPI_LABEL}](" in existing
+            )
+            drops_github = (
+                _is_platform_gap(
+                    parsed_candidate,
+                    candidate in github_releases,
+                    bool(repo_url),
+                    first_github_version,
+                )
+                and f"[{GITHUB_LABEL}](" in existing
+            )
+            if drops_pypi or drops_github:
+                found.add(candidate)
+        return found
+
+    # Retraction gate: never demote an existing "is available" claim to
+    # "is **not available**" on cached data. Both lookups are TTL-cached for a
+    # day, so a snapshot taken before a release landed reports that release as
+    # missing, which is indistinguishable here from one that was never
+    # published. The sanity gates further down catch only a *wholly* empty
+    # result; a stale-but-populated snapshot walks past them, and the window
+    # where it lies is exactly the hours after a release, when this command is
+    # most likely to run. Adding availability stays cheap and cached; dropping
+    # it has to be confirmed live. Running before the date loop means the
+    # spurious "not found on PyPI" warning goes away with it.
+    retracted = retracted_versions()
+    if retracted:
+        logging.warning(
+            f"Cached lookups would retract availability for"
+            f" {', '.join(sorted(retracted))}; re-confirming live."
+        )
+        pypi_data = _load_pypi_releases(
+            package, pypi_package_history, force_refresh=True
+        )
+        first_pypi_version = min(Version(v) for v in pypi_data) if pypi_data else None
+        use_pypi = bool(pypi_data)
+        if repo_url:
+            try:
+                github_releases = get_github_releases(repo_url, force_refresh=True)
+            except GitHubReleasesUnavailable as exc:
+                logging.warning(f"Confirming GitHub lookup failed: {exc}")
+                if fix:
+                    msg = (
+                        f"Refusing to rewrite changelog: cached data would drop"
+                        f" the availability of {', '.join(sorted(retracted))},"
+                        f" and the confirming GitHub lookup failed ({exc})."
+                        f" Re-run when the GitHub API is reachable."
+                    )
+                    logging.error(msg)
+                    emit_annotation(AnnotationLevel.ERROR, msg)
+                    return 2
+            else:
+                first_github_version = (
+                    min(Version(v) for v in github_releases)
+                    if github_releases
+                    else None
+                )
+        still_missing = retracted_versions()
+        if still_missing:
+            # Confirmed against the live APIs: the release really is gone (a
+            # deleted GitHub release, a removed PyPI file). Retracting is then
+            # the correct repair, not a stale-cache artifact.
+            logging.warning(
+                f"Confirmed live: {', '.join(sorted(still_missing))} no longer"
+                " published where the changelog claims."
+            )
+        else:
+            logging.info(
+                "Live lookups confirm the existing availability claims;"
+                " the cache was stale."
+            )
+
     # Detect orphaned versions: present in external sources but missing
     # from the changelog.
     tag_versions = get_all_version_tags()
@@ -1321,17 +1458,11 @@ def lint_changelog_dates(
             # Build the WARNING admonition for platforms where missing.
             # Only warn about gaps: versions that postdate the first
             # release on that platform but are absent from it.
-            pypi_gap = (
-                not on_pypi
-                and bool(package)
-                and first_pypi_version is not None
-                and parsed >= first_pypi_version
+            pypi_gap = _is_platform_gap(
+                parsed, on_pypi, bool(package), first_pypi_version
             )
-            github_gap = (
-                not on_github
-                and bool(repo_url)
-                and first_github_version is not None
-                and parsed >= first_github_version
+            github_gap = _is_platform_gap(
+                parsed, on_github, bool(repo_url), first_github_version
             )
             warning = build_unavailable_admonition(
                 version,