feat: show compat and commit version

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,14 +1,17 @@
 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 pypi_simple import PyPISimple
 
@@ -178,6 +181,11 @@ def collect_plugins(self, plugins, packages, templates):
             desc = "\n".join(meta["info"]["description"].split("\n")[2:])
             version = meta["info"]["version"]
 
+            # Parse Snakemake compatibility from interface package requirements
+            snakemake_version = parse_snakemake_compatibility(
+                meta["info"].get("requires_dist")
+            )
+
             # convert to rst
             desc = m2r2.convert(desc)
 
@@ -225,6 +233,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 +242,14 @@ 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
+            )
+
             settings = {}
             aux_info = {}
 
@@ -257,6 +274,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 +331,24 @@ 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
+
+
 def collect_plugins():
     templates = Environment(
         loader=FileSystemLoader("_templates"),
@@ -372,3 +411,101 @@ 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
+
+
+def parse_snakemake_compatibility(requires_dist: list[str] | None) -> str | None:
+    """Parse Snakemake version compatibility from interface package requirements.
+
+    The major version of interface packages matches the major version of Snakemake.
+    For example, snakemake-interface-executor-plugins 9.x is compatible with Snakemake 9.x.
+
+    Returns version constraint like ">=9.0" or None if not found.
+    """
+    if not requires_dist:
+        return None
+
+    # Look for any interface plugin dependency
+    interface_pattern = r"snakemake-interface-(?:executor|storage|report|logger|scheduler)-plugins\s*(?:\()?([><=!~\d\.,\s<>]+)"
+
+    for dep in requires_dist:
+        match = re.search(interface_pattern, dep)
+        if match:
+            constraint = match.group(1).strip()
+            # get the major version from a constraint: ">=9.0.0,<10.0.0"
+            major_version_match = re.search(r">=?(\d+)\.", constraint)
+            if major_version_match:
+                major_version = major_version_match.group(1)
+                # version for interface matches major Snakemake ver
+                return f">={major_version}.0"
+
+    return None