Shorten the release PR's unshippable-dependency banner

A paragraph, a docs link and a four-column table read as chatter in a pull
request whose body is otherwise a five-step checklist. The banner is now one
line naming each blocked package, linked to the line declaring it at the
commit the body was rendered from. The long form stays in the `lint-deps`
report, where a reader came for the diagnosis.

Author: kdeldycke

changelog.md

@@ -5,6 +5,7 @@
 > [!WARNING]
 > This version is **not released yet** and is under active development.
 
+- The release PR's unshippable-dependency warning is now a single line naming each package, each linked to the line declaring it, instead of a paragraph and a four-column table.
 - The bundled `[tool.typos]` config now accepts `PNGs`, which typos otherwise splits and rewrites to `ONGs`.
 
 ## [`7.12.1` (2026-08-15)](https://github.com/kdeldycke/repomatic/compare/v7.12.0...v7.12.1)

repomatic/cli.py

@@ -1170,11 +1170,16 @@ def _review_step(key: str) -> str:
     # override built-in flag-driven sources so callers can pass any name.
     def _release_readiness() -> str:
         config = get_tool_config()
+        # Pinned to the commit the body was rendered from, so the line the
+        # banner points at is the line that was read. A branch ref would drift
+        # onto whatever `main` holds when the maintainer clicks it.
+        blob_url = f"{md.repo_url}/blob/{md.sha}" if md.repo_url and md.sha else None
         return build_release_readiness(
             Path("pyproject.toml"),
             Path("uv.lock"),
             config.minimum_release_age,
             allow=config.lint_deps.allow,
+            source_url=blob_url,
         )
 
     arg_sources: dict[str, str | None | Callable[[], str | None]] = {

repomatic/dep_sources.py

@@ -136,6 +136,14 @@
 every other clause byte-for-byte untouched.
 """
 
+TOML_TABLE_HEADER = re.compile(r"\s*\[{1,2}\s*(?P<path>[^]]+?)\s*\]{1,2}\s*$")
+"""A `[table]` or `[[array of tables]]` header, capturing its dotted path.
+
+Enough TOML parsing for {func}`declaration_anchor` to tell which table a line
+sits in. The parsed document cannot answer that: `tomllib` and `tomlkit` both
+return values, and a line number is what a link needs.
+"""
+
 
 @dataclass(frozen=True)
 class ReleaseSwap:
@@ -1107,14 +1115,16 @@ def format_blocker_section(
     findings: list[DepFinding],
     *,
     heading: str = "🚧 Unshippable dependencies",
-    name_urls: dict[str, str] | None = None,
 ) -> str:
     """Format blocking findings as a markdown section.
 
+    The long form, for the `lint-deps` report: a reader who opened that report
+    came for the diagnosis, so it carries the note and the full table. The
+    release PR gets {func}`build_release_readiness` instead, which is the same
+    findings at banner length.
+
     :param findings: Findings from {func}`scan_project`.
-    :param heading: Section heading, emoji included. Pass an empty string to
-        emit the note and table alone, for a caller supplying its own title.
-    :param name_urls: Optional mapping of names to a URL the name links to.
+    :param heading: Section heading, emoji included.
     :return: A markdown string, or an empty string when nothing blocks.
     """
     blocking = [finding for finding in findings if finding.blocking]
@@ -1126,7 +1136,7 @@ def format_blocker_section(
         ("Package", "Source", "Declared in", "Why it cannot ship"),
         [
             (
-                link_name(finding.package, name_urls),
+                f"`{finding.package}`",
                 f"`{finding.kind}`",
                 f"`{finding.location}`",
                 f"{finding.consequence} {finding.remedy}",
@@ -1136,6 +1146,67 @@ def format_blocker_section(
     )
 
 
+def declaration_anchor(
+    finding: DepFinding,
+    pyproject_path: Path,
+    lock_path: Path,
+) -> str:
+    """Locate the declaration behind a finding, as a repository-relative link.
+
+    Only two files can hold one: `uv.lock` for a source the resolver picked,
+    `pyproject.toml` for everything the project wrote itself, dependency
+    floors included.
+
+    :param finding: The finding to locate.
+    :param pyproject_path: Path to the `pyproject.toml` file.
+    :param lock_path: Path to the `uv.lock` file.
+    :return: The file name, suffixed with `#L{n}` once the declaring line is
+        found. A line that cannot be found degrades to the bare file rather
+        than to a guess: an anchor pointing at the wrong line costs the reader
+        more than no anchor at all.
+    """
+    in_lock = finding.location == "uv.lock"
+    path = lock_path if in_lock else pyproject_path
+    # A canonical name separates its parts with "-", where the declaration may
+    # spell any of "-", "_" or "." and pick its own case.
+    stem = "[-_.]+".join(re.escape(part) for part in finding.package.split("-"))
+    # `uv.lock` names a package on the `name` key of its `[[package]]` block;
+    # `pyproject.toml` writes it inside a requirement string or as a table key,
+    # so match it as a bare token there.
+    pattern = re.compile(
+        rf'name = "{stem}"' if in_lock else rf"(?<![\w.-]){stem}(?![\w-])",
+        re.IGNORECASE,
+    )
+    try:
+        lines = path.read_text(encoding="UTF-8").splitlines()
+    except OSError:
+        return path.name
+
+    first = 0
+    best = 0
+    best_depth = -1
+    table = ""
+    for number, line in enumerate(lines, start=1):
+        header = TOML_TABLE_HEADER.match(line)
+        if header:
+            table = header["path"]
+        if not pattern.search(line):
+            continue
+        if not first:
+            first = number
+        # A package is named wherever it is required, so a plain first-match
+        # search lands on the requirement rather than on the source override
+        # that made it unshippable. Prefer the deepest table the finding's own
+        # location sits under: that is the declaration to edit, where the
+        # others merely mention the package.
+        in_scope = finding.location == table or finding.location.startswith(f"{table}.")
+        if table and in_scope and len(table) > best_depth:
+            best, best_depth = number, len(table)
+
+    number = best or first
+    return f"{path.name}#L{number}" if number else path.name
+
+
 RELEASE_READY_SENTENCE = "This PR is ready to be merged. "
 """How the release checklist opens when nothing blocks.
 
@@ -1144,11 +1215,25 @@ def format_blocker_section(
 """
 
 
+UNSHIPPABLE_BANNER_LEAD = (
+    "Do not merge yet: this release would ship dependencies its users cannot install:"
+)
+"""Opening of the blocked form of the release PR's verdict.
+
+The banner is a verdict, not a report: it says what is wrong and names what to
+open. Everything else the finding carries (why the source is unshippable, what
+to do about it, the general rule) reads as chatter in a pull request whose
+body is otherwise a five-step checklist, and it is one click away in the
+`lint-deps` report {func}`format_blocker_section` renders.
+"""
+
+
 def build_release_readiness(
     pyproject_path: Path,
     lock_path: Path,
     window: str,
     allow: dict[str, str] | None = None,
+    source_url: str | None = None,
 ) -> str:
     """Build the release PR's opening verdict.
 
@@ -1177,20 +1262,34 @@ def build_release_readiness(
     :param lock_path: Path to the `uv.lock` file.
     :param window: Cooldown window, from `[tool.repomatic] minimum-release-age`.
     :param allow: Package name to its `lint-deps.allow` reason.
-    :return: {data}`RELEASE_READY_SENTENCE`, or a GitHub-flavored markdown
-        `[!CAUTION]` blockquote listing what blocks the release.
+    :param source_url: Blob URL the declarations hang off, without a trailing
+        slash (like ``{repo_url}/blob/{sha}``). Each package links into it. A
+        caller with no commit to point at passes nothing, and the packages
+        render with their file and line as plain text instead.
+    :return: {data}`RELEASE_READY_SENTENCE`, or a one-line GitHub-flavored
+        markdown `[!CAUTION]` blockquote naming what blocks the release.
     """
-    section = format_blocker_section(
-        scan_project(pyproject_path, lock_path, window, allow=allow),
-        heading="",
-    )
-    if not section:
+    blocking = [
+        finding
+        for finding in scan_project(pyproject_path, lock_path, window, allow=allow)
+        if finding.blocking
+    ]
+    if not blocking:
         return RELEASE_READY_SENTENCE
-    quoted = "\n".join(f"> {line}".rstrip() for line in section.splitlines())
-    return (
-        "> [!CAUTION]\n"
-        "> **Do not merge yet: this release would ship dependencies its users"
-        " cannot install.**\n"
-        ">\n"
-        f"{quoted}\n\n"
+    # One link per package: a floor and a source override on the same package
+    # send the reader to the same file, and a name repeated in a one-line
+    # banner reads as two separate problems. Findings arrive sorted by package
+    # then location, so the first one kept is the one nearest to an edit.
+    anchors: dict[str, str] = {}
+    for finding in blocking:
+        if finding.package not in anchors:
+            anchors[finding.package] = declaration_anchor(
+                finding, pyproject_path, lock_path
+            )
+    links = ", ".join(
+        f"[`{package}`]({source_url}/{anchor})"
+        if source_url
+        else f"`{package}` ({anchor})"
+        for package, anchor in anchors.items()
     )
+    return f"> [!CAUTION]\n> **{UNSHIPPABLE_BANNER_LEAD}** {links}\n\n"

tests/test_dep_sources.py

@@ -25,7 +25,9 @@
 from repomatic import dep_sources
 from repomatic.config import Config
 from repomatic.dep_sources import (
+    BLOCKER_SECTION_NOTE,
     RELEASE_READY_SENTENCE,
+    UNSHIPPABLE_BANNER_LEAD,
     ReleaseSwap,
     SourceKind,
     apply_release_swaps,
@@ -674,13 +676,32 @@ def test_release_readiness_flips_the_pr_opening(tmp_path: Path) -> None:
     )
     banner = build_release_readiness(pyproject, lock, "1 week")
     assert banner.startswith("> [!CAUTION]")
-    assert "Do not merge yet" in banner
-    assert "cherry" in banner
-    # Every line of the table is quoted, or GitHub renders half of it outside
-    # the admonition.
-    assert all(
-        line.startswith(">") for line in banner.strip().splitlines() if line.strip()
+    assert UNSHIPPABLE_BANNER_LEAD in banner
+    # A verdict, not a report: the alert marker and one line naming the
+    # package, with none of the prose or the table `lint-deps` renders.
+    lines = [line for line in banner.strip().splitlines() if line.strip()]
+    assert len(lines) == 2
+    assert BLOCKER_SECTION_NOTE not in banner
+    assert "| Package |" not in banner
+    # Both lines stay quoted, or GitHub renders half of it outside the
+    # admonition.
+    assert all(line.startswith(">") for line in lines)
+
+    # The package points at the line declaring it, linked when the caller
+    # supplies a commit to hang the blob URL off, plain text otherwise.
+    declared_line = next(
+        number
+        for number, line in enumerate(
+            pyproject.read_text(encoding="UTF-8").splitlines(), start=1
+        )
+        if line.startswith("cherry =")
+    )
+    declaration = f"pyproject.toml#L{declared_line}"
+    assert f"`cherry` ({declaration})" in banner
+    linked = build_release_readiness(
+        pyproject, lock, "1 week", source_url="https://x/repo/blob/deadbeef"
     )
+    assert f"[`cherry`](https://x/repo/blob/deadbeef/{declaration})" in linked
 
 
 def test_project_ships_only_released_dependencies() -> None: