feat: show compat and commit version

we display 3 additional badges:

- last commit in git repo, with link
- last updated for the git repo (color-coded for freshness)
- lower snakemake version that depends on the same version of the
  interface that the plugin depends on

Author: btraven00

source/_static/custom.css

@@ -1,9 +1,11 @@
 .image-reference img {
     display: inline;
+    margin-right: 4px;
 }
 
 .image-reference {
     border-bottom: none !important;
+    font-size: 0;
 }
 
 table code.literal {

source/_templates/executor_plugin.rst.j2

@@ -3,7 +3,7 @@
 {% block type %}executor{% endblock %}
 
 {% block usage %}
-In order to use the plugin, run Snakemake (>=8.0) in the folder where your workflow code and config resides (containing either ``workflow/Snakefile`` or ``Snakefile``) with the corresponding value for the executor flag::
+In order to use the plugin, run Snakemake ({{ snakemake_version if snakemake_version else ">=8.0" }}) in the folder where your workflow code and config resides (containing either ``workflow/Snakefile`` or ``Snakefile``) with the corresponding value for the executor flag::
 
     snakemake --executor {{ plugin_name }} --default-resources --jobs N ...
 

source/_templates/logger_plugin.rst.j2

@@ -3,9 +3,9 @@
 {% block type %}logger{% endblock %}
 
 {% block usage %}
-In order to use the plugin, run Snakemake (>=9.0) with the corresponding value for the logger flag::
+In order to use the plugin, run Snakemake ({{ snakemake_version if snakemake_version else ">=9.0" }}) with the corresponding value for the logger flag::
 
     snakemake --logger {{ plugin_name }} ...
 
 with ``...`` being any additional arguments you want to use.
-{% endblock %}
+{% endblock %}

source/_templates/plugin_base.rst.j2

@@ -4,26 +4,36 @@
 Snakemake {% block type %}{% endblock %} plugin: {{ plugin_name }}
 ###########################################
 
-{% if repository is not none %}
+{% if repository is not none -%}
 .. image:: https://img.shields.io/badge/repository-{{ repository_type }}-blue?color=%23022c22
    :target: {{ repository }}
-{% else %}
+{% else -%}
 .. image:: https://img.shields.io/badge/repository-unknown-blue?color=%23022c22
    :target: #
-{% endif %}
-
-{% for author in authors %}
+{% endif -%}
+{% if commit_info is not none -%}
+.. image:: https://img.shields.io/badge/last_commit-{{ commit_info["sha"] }}-green?color={{ commit_age_color }}
+   :alt: Last commit
+   :target: {{ repository }}
+.. image:: https://img.shields.io/badge/last_updated-{{ commit_date_label }}-green?color={{ commit_age_color }}
+   :alt: Last updated
+   :target: {{ repository }}
+{% endif -%}
+{% for author in authors -%}
 .. image:: https://img.shields.io/badge/author-{{author|replace("-","--")|urlencode}}-purple?color=%23064e3b
    :target: https://pypi.org/project/{{ package_name }}
-{% endfor %}
-
+{% endfor -%}
 .. image:: https://img.shields.io/pypi/v/{{ package_name }}?color=%23047857
    :alt: PyPI - Version
    :target: https://pypi.org/project/{{ package_name }}
-
 .. image:: https://img.shields.io/pypi/l/{{ package_name }}?color=%2310b981
    :alt: PyPI - License
    :target: https://pypi.org/project/{{ package_name }}
+{% if snakemake_version is not none %}
+.. image:: https://img.shields.io/badge/snakemake-{{ snakemake_version|replace("-", "--") }}-blue?color=%230ea5e9
+   :alt: Snakemake
+   :target: https://snakemake.readthedocs.io
+{% endif %}
 
 {% if repository is not none and not repository.startswith("https://github.com/snakemake/") %}
 .. warning::

source/_templates/report_plugin.rst.j2

@@ -3,9 +3,9 @@
 {% block type %}report{% endblock %}
 
 {% block usage %}
-In order to use the plugin, run Snakemake (>=8.5) with the corresponding value for the reporter flag::
+In order to use the plugin, run Snakemake ({{ snakemake_version if snakemake_version else ">=8.5" }}) with the corresponding value for the reporter flag::
 
     snakemake --reporter {{ plugin_name }} ...
 
 with ``...`` being any additional arguments you want to use.
-{% endblock %}
+{% endblock %}

source/_templates/scheduler_plugin.rst.j2

@@ -3,7 +3,7 @@
 {% block type %}scheduler{% endblock %}
 
 {% block usage %}
-In order to use the plugin, run Snakemake (>=9.0) with the corresponding value for the scheduler flag::
+In order to use the plugin, run Snakemake ({{ snakemake_version if snakemake_version else ">=9.0" }}) with the corresponding value for the scheduler flag::
 
     snakemake --scheduler {{ plugin_name }} ...
 

source/collect_plugins.py

@@ -1,15 +1,20 @@
 from abc import ABC, abstractmethod
 from collections import defaultdict
+from datetime import datetime, timezone
 import json
 import os
+import re
 from pathlib import Path
 import shutil
 import subprocess
 import sys
 import tempfile
 import textwrap
 from typing import Any, Dict, List
+import urllib.parse
 import uuid
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
 from pypi_simple import PyPISimple
 
 import requests
@@ -152,7 +157,7 @@ def plugin_type(self) -> str:
     def aux_info(self, metadata_collector) -> Dict[str, Any]:
         return {}
 
-    def collect_plugins(self, plugins, packages, templates):
+    def collect_plugins(self, plugins, packages, templates, snakemake_compat_index):
         plugin_type = self.plugin_type()
         plugin_dir = Path("plugins") / plugin_type
         if plugin_dir.exists():
@@ -225,6 +230,7 @@ def get_setting_meta(setting, key, default="", verb=False):
                     repository_type = "gitlab"
             docs_intro = get_docs(repository, section="intro")
             docs_further = get_docs(repository, section="further")
+
             if repository is not None and docs_intro is None and docs_further is None:
                 docs_warning = (
                     f"No documentation found in repository {repository}. The plugin should "
@@ -233,6 +239,18 @@ def get_setting_meta(setting, key, default="", verb=False):
                     "auto-generated usage instructions presented in this catalog."
                 )
 
+            commit_info = get_commit(repository, repository_type)
+            commit_date_label = (
+                _commit_date_label(commit_info["date"]) if commit_info else None
+            )
+            commit_age_color = (
+                _commit_age_color(commit_info["date"]) if commit_info else None
+            )
+
+            snakemake_version = _plugin_min_snakemake(
+                meta["info"].get("requires_dist"), snakemake_compat_index
+            )
+
             settings = {}
             aux_info = {}
 
@@ -257,6 +275,10 @@ def get_setting_meta(setting, key, default="", verb=False):
                 authors=authors,
                 repository=repository,
                 repository_type=repository_type,
+                commit_info=commit_info,
+                commit_age_color=commit_age_color,
+                commit_date_label=commit_date_label,
+                snakemake_version=snakemake_version,
                 meta=meta,
                 desc=desc,
                 docs_intro=docs_intro,
@@ -310,6 +332,114 @@ def plugin_type(self):
         return "scheduler"
 
 
+def _commit_date_label(date_str: str) -> str:
+    """Return a shields.io-safe date label like 'March_2026' from an ISO date string."""
+    return datetime.fromisoformat(date_str.replace("Z", "+00:00")).strftime("%B_%Y")
+
+
+def _commit_age_color(date_str: str) -> str:
+    """Return a shields.io color hex based on how old the commit date is."""
+    dt = datetime.fromisoformat(date_str.replace("Z", "+00:00"))
+    now = datetime.now(timezone.utc)
+    months = (now.year - dt.year) * 12 + (now.month - dt.month)
+    if months < 6:
+        return "%2316a34a"  # green
+    elif months < 24:
+        return "%23ea580c"  # orange
+    else:
+        return "%23dc2626"  # red
+
+
+_INTERFACE_PKG_RE = re.compile(
+    r"(snakemake-interface-(?:executor|storage|report|logger|scheduler)-plugins)"
+    r"\s*\(?([^)]+)"
+)
+
+
+def _build_snakemake_compat_index() -> list[tuple]:
+    """Fetch Snakemake release metadata from PyPI once and build a compatibility index.
+
+    Returns a sorted list of (snakemake_version, interface_pkg, lower, upper) tuples
+    where lower/upper are Version objects (or None) from snakemake's interface requirement.
+    """
+    print("Building Snakemake compatibility index...", file=sys.stderr)
+    meta = pypi_api("https://pypi.org/pypi/snakemake/json")
+    all_versions = sorted(
+        [
+            v
+            for v in meta["releases"]
+            if not Version(v).is_prerelease and Version(v) >= Version("8.0.0")
+        ],
+        key=Version,
+    )
+
+    # Only fetch first release per major.minor to minimise API calls
+    seen_minor: set[tuple] = set()
+    representative: list[str] = []
+    for v in all_versions:
+        p = Version(v)
+        key = (p.major, p.minor)
+        if key not in seen_minor:
+            seen_minor.add(key)
+            representative.append(v)
+
+    entries = []
+    for snakemake_ver in representative:
+        try:
+            ver_meta = pypi_api(f"https://pypi.org/pypi/snakemake/{snakemake_ver}/json")
+        except MetadataError:
+            continue
+        for dep in ver_meta["info"].get("requires_dist") or []:
+            m = _INTERFACE_PKG_RE.search(dep)
+            if not m:
+                continue
+            iface_pkg = m.group(1)
+            spec = SpecifierSet(m.group(2).strip())
+            lower = upper = None
+            for s in spec:
+                v = Version(s.version)
+                if s.operator in (">=", ">"):
+                    if lower is None or v > lower:
+                        lower = v
+                elif s.operator in ("<", "<="):
+                    if upper is None or v < upper:
+                        upper = v
+            entries.append((Version(snakemake_ver), iface_pkg, lower, upper))
+
+    return sorted(entries, key=lambda e: e[0])
+
+
+def _plugin_min_snakemake(
+    requires_dist: list[str] | None,
+    compat_index: list[tuple],
+) -> str | None:
+    """Return the minimum Snakemake version (as '>=X.Y') compatible with a plugin."""
+    if not requires_dist:
+        return None
+
+    plugin_lower = None
+    plugin_iface = None
+    for dep in requires_dist:
+        m = _INTERFACE_PKG_RE.search(dep)
+        if m:
+            plugin_iface = m.group(1)
+            for s in SpecifierSet(m.group(2).strip()):
+                if s.operator in (">=", ">"):
+                    v = Version(s.version)
+                    if plugin_lower is None or v > plugin_lower:
+                        plugin_lower = v
+            break
+
+    if plugin_lower is None or plugin_iface is None:
+        return None
+
+    for snakemake_ver, iface_pkg, _lower, upper in compat_index:
+        if iface_pkg == plugin_iface and upper is not None and plugin_lower < upper:
+            return f">={snakemake_ver.major}.{snakemake_ver.minor}"
+
+    return None
+
+
 def collect_plugins():
     templates = Environment(
         loader=FileSystemLoader("_templates"),
@@ -319,6 +449,7 @@ def collect_plugins():
     )
 
     plugins = defaultdict(list)
+    snakemake_compat_index = _build_snakemake_compat_index()
 
     with PyPISimple() as pypi_client:
         packages = pypi_client.get_index_page().projects
@@ -330,7 +461,9 @@ def collect_plugins():
         LoggerPluginCollector,
         SchedulerPluginCollector,
     ):
-        collector().collect_plugins(plugins, packages, templates)
+        collector().collect_plugins(
+            plugins, packages, templates, snakemake_compat_index
+        )
 
     with open("index.rst", "w") as f:
         f.write(templates.get_template("index.rst.j2").render(plugins=plugins))
@@ -372,3 +505,73 @@ def retrieve():
         return m2r2.convert(retrieved, renderer=renderer)
     else:
         return None
+
+
+def _fetch_commit_info(repository: str, repository_type: str, branch: str):
+    """Fetch commit info for a specific branch using regex to parse URLs.
+
+    Args:
+        repository: The repository URL
+        repository_type: Either "github" or "gitlab"
+        branch: The branch name to query
+
+    Returns:
+        Dict with 'sha' and 'date' keys, or None if request fails
+    """
+    if repository_type == "github":
+        match = re.match(r"https://github\.com/([^/]+)/([^/]+?)/?$", repository)
+        if not match:
+            return None
+        owner, repo = match.groups()
+
+        api_url = f"https://api.github.com/repos/{owner}/{repo}/commits/{branch}?per_page=1&page=1"
+        response = requests.get(api_url)
+        if response.status_code == 200:
+            data = response.json()
+            return {
+                "sha": data["sha"][:7],
+                "date": data["commit"]["author"]["date"],
+            }
+
+    elif repository_type == "gitlab":
+        match = re.match(r"https://gitlab\.com/(.+?)/?$", repository)
+        if not match:
+            return None
+        project_path = match.group(1)
+
+        encoded_path = urllib.parse.quote(project_path, safe="")
+        api_url = f"https://gitlab.com/api/v4/projects/{encoded_path}/repository/commits/{branch}"
+        response = requests.get(api_url)
+        if response.status_code == 200:
+            data = response.json()
+            return {
+                "sha": data["short_id"],
+                "date": data["committed_date"],
+            }
+
+    return None
+
+
+def get_commit(
+    repository: str | None, repository_type: str | None, branches=["main", "master"]
+):
+    """Fetch the latest commit information from a GitHub or GitLab repository.
+
+    Returns a dict with commit info:
+        - sha: short commit hash (7 chars)
+        - date: commit date
+    Returns None if repository is None or if the request fails.
+    """
+    if repository is None or repository_type is None:
+        return None
+
+    for branch in branches:
+        try:
+            result = _fetch_commit_info(repository, repository_type, branch)
+            if result is not None:
+                return result
+        except Exception:
+            # Continue to next branch on any error
+            continue
+
+    return None