gha-utils 4.24.0__py3-none-any.whl

gha_utils/metadata.py

@@ -0,0 +1,1693 @@
+# 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.
+
+"""Extract metadata from repository and Python projects to be used by GitHub workflows.
+
+The following variables are `printed to the environment file
+<https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#environment-files>`_:
+
+```text
+is_bot=false
+new_commits=346ce664f055fbd042a25ee0b7e96702e95 6f27db47612aaee06fdf08744b09a9f5f6c2
+release_commits=6f27db47612aaee06fdf08744b09a9f5f6c2
+mailmap_exists=true
+gitignore_exists=true
+python_files=".github/update_mailmap.py" ".github/metadata.py" "setup.py"
+json_files=
+yaml_files="config.yaml" ".github/workflows/lint.yaml" ".github/workflows/test.yaml"
+workflow_files=".github/workflows/lint.yaml" ".github/workflows/test.yaml"
+doc_files="changelog.md" "readme.md" "docs/license.md"
+markdown_files="changelog.md" "readme.md" "docs/license.md"
+image_files=
+zsh_files=
+is_python_project=true
+package_name=click-extra
+blacken_docs_params=--target-version py37 --target-version py38
+mypy_params=--python-version 3.7
+current_version=2.0.1
+released_version=2.0.0
+is_sphinx=true
+active_autodoc=true
+release_notes=[🐍 Available on PyPi](https://pypi.org/project/click-extra/2.21.3).
+new_commits_matrix={
+    "commit": [
+        "346ce664f055fbd042a25ee0b7e96702e95",
+        "6f27db47612aaee06fdf08744b09a9f5f6c2"
+    ],
+    "include": [
+        {
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "short_sha": "346ce66",
+            "current_version": "2.0.1"
+        },
+        {
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "short_sha": "6f27db4",
+            "current_version": "2.0.0"
+        }
+    ]
+}
+release_commits_matrix={
+    "commit": ["6f27db47612aaee06fdf08744b09a9f5f6c2"],
+    "include": [
+        {
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "short_sha": "6f27db4",
+            "current_version": "2.0.0"
+        }
+    ]
+}
+build_targets=[
+    {
+        "target": "linux-arm64",
+        "os": "ubuntu-24.04-arm",
+        "platform_id": "linux",
+        "arch": "arm64",
+        "extension": "bin"
+    },
+    {
+        "target": "linux-x64",
+        "os": "ubuntu-slim",
+        "platform_id": "linux",
+        "arch": "x64",
+        "extension": "bin"
+    },
+    {
+        "target": "macos-arm64",
+        "os": "macos-26",
+        "platform_id": "macos",
+        "arch": "arm64",
+        "extension": "bin"
+    },
+    {
+        "target": "macos-x64",
+        "os": "macos-15-intel",
+        "platform_id": "macos",
+        "arch": "x64",
+        "extension": "bin"
+    },
+    {
+        "target": "windows-arm64",
+        "os": "windows-11-arm",
+        "platform_id": "windows",
+        "arch": "arm64",
+        "extension": "exe"
+    },
+    {
+        "target": "windows-x64",
+        "os": "windows-2025",
+        "platform_id": "windows",
+        "arch": "x64",
+        "extension": "exe"
+    }
+]
+nuitka_matrix={
+    "os": [
+        "ubuntu-24.04-arm",
+        "ubuntu-slim",
+        "macos-26",
+        "macos-15-intel",
+        "windows-11-arm",
+        "windows-2025"
+    ],
+    "entry_point": ["mpm"],
+    "commit": [
+        "346ce664f055fbd042a25ee0b7e96702e95",
+        "6f27db47612aaee06fdf08744b09a9f5f6c2"
+    ],
+    "include": [
+        {
+            "target": "linux-arm64",
+            "os": "ubuntu-24.04-arm",
+            "platform_id": "linux",
+            "arch": "arm64",
+            "extension": "bin"
+        },
+        {
+            "target": "linux-x64",
+            "os": "ubuntu-slim",
+            "platform_id": "linux",
+            "arch": "x64",
+            "extension": "bin"
+        },
+        {
+            "target": "macos-arm64",
+            "os": "macos-26",
+            "platform_id": "macos",
+            "arch": "arm64",
+            "extension": "bin"
+        },
+        {
+            "target": "macos-x64",
+            "os": "macos-15-intel",
+            "platform_id": "macos",
+            "arch": "x64",
+            "extension": "bin"
+        },
+        {
+            "target": "windows-arm64",
+            "os": "windows-11-arm",
+            "platform_id": "windows",
+            "arch": "arm64",
+            "extension": "exe"
+        },
+        {
+            "target": "windows-x64",
+            "os": "windows-2025",
+            "platform_id": "windows",
+            "arch": "x64",
+            "extension": "exe"
+        },
+        {
+            "entry_point": "mpm",
+            "cli_id": "mpm",
+            "module_id": "meta_package_manager.__main__",
+            "callable_id": "main",
+            "module_path": "meta_package_manager/__main__.py"
+        },
+        {
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "short_sha": "346ce66",
+            "current_version": "2.0.0"
+        },
+        {
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "short_sha": "6f27db4",
+            "current_version": "1.9.1"
+        },
+        {
+            "os": "ubuntu-24.04-arm",
+            "entry_point": "mpm",
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "bin_name": "mpm-linux-arm64-346ce66.bin"
+        },
+        {
+            "os": "ubuntu-24.04-arm",
+            "entry_point": "mpm",
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "bin_name": "mpm-linux-arm64-6f27db4.bin"
+        },
+        {
+            "os": "ubuntu-slim",
+            "entry_point": "mpm",
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "bin_name": "mpm-linux-x64-346ce66.bin"
+        },
+        {
+            "os": "ubuntu-slim",
+            "entry_point": "mpm",
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "bin_name": "mpm-linux-x64-6f27db4.bin"
+        },
+        {
+            "os": "macos-26",
+            "entry_point": "mpm",
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "bin_name": "mpm-macos-arm64-346ce66.bin"
+        },
+        {
+            "os": "macos-26",
+            "entry_point": "mpm",
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "bin_name": "mpm-macos-arm64-6f27db4.bin"
+        },
+        {
+            "os": "macos-15-intel",
+            "entry_point": "mpm",
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "bin_name": "mpm-macos-x64-346ce66.bin"
+        },
+        {
+            "os": "macos-15-intel",
+            "entry_point": "mpm",
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "bin_name": "mpm-macos-x64-6f27db4.bin"
+        },
+        {
+            "os": "windows-11-arm",
+            "entry_point": "mpm",
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "bin_name": "mpm-windows-arm64-346ce66.bin"
+        },
+        {
+            "os": "windows-11-arm",
+            "entry_point": "mpm",
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "bin_name": "mpm-windows-arm64-6f27db4.bin"
+        },
+        {
+            "os": "windows-2025",
+            "entry_point": "mpm",
+            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+            "bin_name": "mpm-windows-x64-346ce66.exe"
+        },
+        {
+            "os": "windows-2025",
+            "entry_point": "mpm",
+            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+            "bin_name": "mpm-windows-x64-6f27db4.exe"
+        },
+        {"state": "stable"}
+    ]
+}
+```
+
+.. warning::
+    Fields with serialized lists and dictionaries, like ``new_commits_matrix``,
+    ``build_targets`` or ``nuitka_matrix``, are pretty-printed in the example above for
+    readability. They are inlined in the actual output and not formatted this way.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import logging
+import os
+import re
+import tomllib
+from collections.abc import Iterable
+from enum import StrEnum
+from functools import cached_property
+from operator import itemgetter
+from pathlib import Path
+from random import randint
+from re import escape
+
+from bumpversion.config import get_configuration  # type: ignore[import-untyped]
+from bumpversion.config.files import find_config_file  # type: ignore[import-untyped]
+from bumpversion.show import resolve_name  # type: ignore[import-untyped]
+from extra_platforms import is_github_ci
+from gitdb.exc import BadName  # type: ignore[import-untyped]
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+from py_walk import get_parser_from_file
+from py_walk.models import Parser
+from pydriller import Commit, Git, Repository  # type: ignore[import-untyped]
+from pyproject_metadata import ConfigurationError, StandardMetadata
+from wcmatch.glob import (
+    BRACE,
+    DOTGLOB,
+    FOLLOW,
+    GLOBSTAR,
+    GLOBTILDE,
+    NEGATE,
+    NODIR,
+    iglob,
+)
+
+from .matrix import Matrix
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Any, Final
+
+
+SHORT_SHA_LENGTH = 7
+"""Default SHA length hard-coded to ``7``.
+
+.. caution::
+
+    The `default is subject to change <https://stackoverflow.com/a/21015031>`_ and
+    depends on the size of the repository.
+"""
+
+MAILMAP_PATH = Path(".mailmap")
+
+GITIGNORE_PATH = Path(".gitignore")
+
+NUITKA_BUILD_TARGETS = {
+    "linux-arm64": {
+        "os": "ubuntu-24.04-arm",
+        "platform_id": "linux",
+        "arch": "arm64",
+        "extension": "bin",
+    },
+    "linux-x64": {
+        "os": "ubuntu-slim",
+        "platform_id": "linux",
+        "arch": "x64",
+        "extension": "bin",
+    },
+    "macos-arm64": {
+        "os": "macos-26",
+        "platform_id": "macos",
+        "arch": "arm64",
+        "extension": "bin",
+    },
+    "macos-x64": {
+        "os": "macos-15-intel",
+        "platform_id": "macos",
+        "arch": "x64",
+        "extension": "bin",
+    },
+    "windows-arm64": {
+        "os": "windows-11-arm",
+        "platform_id": "windows",
+        "arch": "arm64",
+        "extension": "exe",
+    },
+    "windows-x64": {
+        "os": "windows-2025",
+        "platform_id": "windows",
+        "arch": "x64",
+        "extension": "exe",
+    },
+}
+"""List of GitHub-hosted runners used for Nuitka builds.
+
+The key of the dictionary is the target name, which is used as a short name for
+user-friendlyness. As such, it is used to name the compiled binary.
+
+Values are dictionaries with the following keys:
+
+- ``os``: Operating system name, as used in `GitHub-hosted runners
+    <https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/choosing-the-runner-for-a-job#standard-github-hosted-runners-for-public-repositories>`_.
+
+    .. hint::
+        We choose to run the compilation only on the latest supported version of each
+        OS, for each architecture. Note that macOS and Windows do not have the latest
+        version available for each architecture.
+
+- ``platform_id``: Platform identifier, as defined by `Extra Platform
+  <https://github.com/kdeldycke/extra-platforms>`_.
+
+- ``arch``: Architecture identifier.
+
+    .. note::
+        Architecture IDs are `inspired from those specified for self-hosted runners
+        <https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/supported-architectures-and-operating-systems-for-self-hosted-runners#supported-processor-architectures>`_
+
+    .. note::
+        Maybe we should just adopt `target triple
+        <https://mcyoung.xyz/2025/04/14/target-triples/>`_.
+
+- ``extension``: File extension of the compiled binary.
+"""
+
+
+FLAT_BUILD_TARGETS = [
+    {"target": target_id} | target_data
+    for target_id, target_data in NUITKA_BUILD_TARGETS.items()
+]
+"""List of build targets in a flat format, suitable for matrix inclusion."""
+
+
+WorkflowEvent = StrEnum(
+    "WorkflowEvent",
+    (
+        "branch_protection_rule",
+        "check_run",
+        "check_suite",
+        "create",
+        "delete",
+        "deployment",
+        "deployment_status",
+        "discussion",
+        "discussion_comment",
+        "fork",
+        "gollum",
+        "issue_comment",
+        "issues",
+        "label",
+        "merge_group",
+        "milestone",
+        "page_build",
+        "project",
+        "project_card",
+        "project_column",
+        "public",
+        "pull_request",
+        "pull_request_comment",
+        "pull_request_review",
+        "pull_request_review_comment",
+        "pull_request_target",
+        "push",
+        "registry_package",
+        "release",
+        "repository_dispatch",
+        "schedule",
+        "status",
+        "watch",
+        "workflow_call",
+        "workflow_dispatch",
+        "workflow_run",
+    ),
+)
+"""Workflow events that cause a workflow to run.
+
+`List of events
+<https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows>`_.
+"""
+
+
+Dialect = StrEnum("Dialect", ("github", "json"))
+"""Dialect in which metadata can be formatted to."""
+
+
+class TargetVersion(StrEnum):
+    """List of Python 3 minor versions supported by Black.
+
+    `Mirrors official implementation from black.mode.TargetVersion
+    <https://github.com/psf/black/blob/main/src/black/mode.py>`_.
+    """
+
+    PY33 = "3.3"
+    PY34 = "3.4"
+    PY35 = "3.5"
+    PY36 = "3.6"
+    PY37 = "3.7"
+    PY38 = "3.8"
+    PY39 = "3.9"
+    PY310 = "3.10"
+    PY311 = "3.11"
+    PY312 = "3.12"
+    PY313 = "3.13"
+    PY314 = "3.14"
+
+
+MYPY_VERSION_MIN: Final = (3, 8)
+"""Earliest version supported by Mypy's ``--python-version 3.x`` parameter.
+
+`Sourced from Mypy original implementation
+<https://github.com/python/mypy/blob/master/mypy/defaults.py>`_.
+"""
+
+
+# Silence overly verbose debug messages from py-walk logger.
+logging.getLogger("py_walk").setLevel(logging.WARNING)
+
+
+class JSONMetadata(json.JSONEncoder):
+    """Custom JSON encoder for metadata serialization."""
+
+    def default(self, o: Any) -> Any:
+        if isinstance(o, Matrix):
+            return o.matrix()
+
+        if isinstance(o, Path):
+            return str(o)
+
+        return super().default(o)
+
+
+class Metadata:
+    """Metadata class."""
+
+    def __init__(self, unstable_targets: Iterable[str] | None = None) -> None:
+        """Initialize internal variables."""
+        self.unstable_targets = set()
+        if unstable_targets:
+            self.unstable_targets = set(unstable_targets)
+            assert self.unstable_targets.issubset(NUITKA_BUILD_TARGETS)
+
+    pyproject_path = Path() / "pyproject.toml"
+    sphinx_conf_path = Path() / "docs" / "conf.py"
+
+    @cached_property
+    def github_context(self) -> dict[str, Any]:
+        """Load GitHub context from the environment.
+
+        Expect ``GITHUB_CONTEXT`` to be set as part of the environment. I.e., adds the
+        following as part of your job step calling this script:
+
+        .. code-block:: yaml
+
+            - name: Project metadata
+              id: project-metadata
+              env:
+                GITHUB_CONTEXT: ${{ toJSON(github) }}
+              run: |
+                gha-utils --verbosity DEBUG metadata --overwrite "$GITHUB_OUTPUT"
+
+        .. todo::
+            Try to remove reliance on GitHub context entirely so we can eliminate the
+            JSON/env hack above.
+        """
+        if "GITHUB_CONTEXT" not in os.environ:
+            if is_github_ci():
+                message = (
+                    "Missing GitHub context in environment. "
+                    "Did you forget to set GITHUB_CONTEXT?"
+                )
+                logging.warning(message)
+            return {}
+        context = json.loads(os.environ["GITHUB_CONTEXT"])
+        logging.debug("--- GitHub context ---")
+        logging.debug(json.dumps(context, indent=4))
+        return context  # type:ignore[no-any-return]
+
+    @cached_property
+    def git(self) -> Git:
+        """Return a PyDriller Git object."""
+        return Git(".")
+
+    def git_stash_count(self) -> int:
+        """Returns the number of stashes."""
+        count = int(
+            self.git.repo.git.rev_list(
+                "--walk-reflogs", "--ignore-missing", "--count", "refs/stash"
+            )
+        )
+        logging.debug(f"Number of stashes in repository: {count}")
+        return count
+
+    def git_deepen(
+        self, commit_hash: str, max_attempts: int = 10, deepen_increment: int = 50
+    ) -> bool:
+        """Deepen a shallow clone until the provided ``commit_hash`` is found.
+
+        Progressively fetches more commits from the current repository until the
+        specified commit is found or max attempts is reached.
+
+        Returns ``True`` if the commit was found, ``False`` otherwise.
+        """
+        for attempt in range(max_attempts):
+            try:
+                _ = self.git.get_commit(commit_hash)
+                if attempt > 0:
+                    logging.info(
+                        f"Found commit {commit_hash} after {attempt} deepen "
+                        "operation(s)."
+                    )
+                return True
+            except (ValueError, BadName) as ex:
+                logging.debug(f"Commit {commit_hash} not found: {ex}")
+
+                current_depth = self.git.total_commits()
+
+                if attempt == max_attempts - 1:
+                    # We've exhausted all attempts
+                    logging.error(
+                        f"Cannot find commit {commit_hash} in repository after "
+                        f"{max_attempts} deepen attempts. "
+                        f"Final depth is {current_depth} commits."
+                    )
+                    return False
+
+                logging.info(
+                    f"Commit {commit_hash} not found at depth {current_depth}."
+                )
+                logging.info(
+                    f"Deepening by {deepen_increment} commits (attempt "
+                    f"{attempt + 1}/{max_attempts})..."
+                )
+
+                try:
+                    self.git.repo.git.fetch(f"--deepen={deepen_increment}")
+                    new_depth = self.git.total_commits()
+                    logging.debug(
+                        f"Repository deepened successfully. New depth: {new_depth}"
+                    )
+                except Exception as ex:
+                    logging.error(f"Failed to deepen repository: {ex}")
+                    return False
+
+        return False
+
+    def commit_matrix(self, commits: Iterable[Commit] | None) -> Matrix | None:
+        """Pre-compute a matrix of commits.
+
+        .. danger::
+            This method temporarily modify the state of the repository to compute
+            version metadata from the past.
+
+            To prevent any loss of uncommitted data, it stashes and unstash the
+            local changes between checkouts.
+
+        The list of commits is augmented with long and short SHA values, as well as
+        current version. Most recent commit is first, oldest is last.
+
+        Returns a ready-to-use matrix structure:
+
+        .. code-block:: python
+            {
+                "commit": [
+                    "346ce664f055fbd042a25ee0b7e96702e95",
+                    "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                ],
+                "include": [
+                    {
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "short_sha": "346ce66",
+                        "current_version": "2.0.1",
+                    },
+                    {
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "short_sha": "6f27db4",
+                        "current_version": "2.0.0",
+                    },
+                ],
+            }
+        """
+        if not commits:
+            return None
+
+        current_commit = self.git.repo.head.commit.hexsha
+
+        # Check if we need to get back in time in the Git log and browse past commits.
+        if len(commits) == 1:  # type: ignore[arg-type]
+            # Is the current commit the one we're looking for?
+            past_commit_lookup = bool(
+                current_commit != commits[0].hash  # type: ignore[index]
+            )
+        # If we have multiple commits then yes, we need to look for past commits.
+        else:
+            past_commit_lookup = True
+
+        # We need to go back in time, but first save the current state of the
+        # repository.
+        if past_commit_lookup:
+            logging.debug(
+                "We need to look into the commit history. Inspect the initial state "
+                "of the repository."
+            )
+
+            if not is_github_ci():
+                raise RuntimeError(
+                    "Local repository manipulations only allowed in CI environment"
+                )
+
+            # Save the initial commit reference and SHA of the repository. The
+            # reference is either the canonical active branch name (i.e. ``main``), or
+            # the commit SHA if the current HEAD commit is detached from a branch.
+            if self.git.repo.head.is_detached:
+                init_ref = current_commit
+            else:
+                init_ref = self.git.repo.active_branch.name
+            logging.debug(f"Initial commit reference: {init_ref}")
+
+            # Try to stash local changes and check if we'll need to unstash them later.
+            counter_before = self.git_stash_count()
+            logging.debug("Try to stash local changes before our series of checkouts.")
+            self.git.repo.git.stash()
+            counter_after = self.git_stash_count()
+            logging.debug(
+                "Stash counter changes after 'git stash' command: "
+                f"{counter_before} -> {counter_after}"
+            )
+            assert counter_after >= counter_before
+            need_unstash = bool(counter_after > counter_before)
+            logging.debug(f"Need to unstash after checkouts: {need_unstash}")
+
+        else:
+            init_ref = None
+            need_unstash = False
+            logging.debug(
+                "No need to look into the commit history: repository is already "
+                f"checked out at {current_commit}"
+            )
+
+        matrix = Matrix()
+        for commit in commits:
+            if past_commit_lookup:
+                logging.debug(f"Checkout to commit {commit.hash}")
+                self.git.checkout(commit.hash)
+
+            commit_metadata = {
+                "commit": commit.hash,
+                "short_sha": commit.hash[:SHORT_SHA_LENGTH],
+            }
+
+            logging.debug(f"Extract project version at commit {commit.hash}")
+            current_version = Metadata.get_current_version()
+            if current_version:
+                commit_metadata["current_version"] = current_version
+
+            matrix.add_variation("commit", [commit.hash])
+            matrix.add_includes(commit_metadata)
+
+        # Restore the repository to its initial state.
+        if past_commit_lookup:
+            logging.debug(f"Restore repository to {init_ref}.")
+            self.git.checkout(init_ref)
+            if need_unstash:
+                logging.debug("Unstash local changes that were previously saved.")
+                self.git.repo.git.stash("pop")
+
+        return matrix
+
+    @cached_property
+    def event_type(self) -> WorkflowEvent | None:
+        """Returns the type of event that triggered the workflow run.
+
+        .. caution::
+            This property is based on a crude heuristics as it only looks at the value
+            of the ``GITHUB_BASE_REF`` environment variable. Which is `only set when
+            the event that triggers a workflow run is either pull_request or
+            pull_request_target
+            <https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables>`_.
+
+        .. todo::
+            Add detection of all workflow trigger events.
+        """
+        if not is_github_ci():
+            logging.warning(
+                "Cannot guess event type because we're not in a CI environment."
+            )
+            return None
+        if "GITHUB_BASE_REF" not in os.environ:
+            logging.warning(
+                "Cannot guess event type because no GITHUB_BASE_REF env var found."
+            )
+            return None
+
+        if bool(os.environ.get("GITHUB_BASE_REF")):
+            return WorkflowEvent.pull_request
+        return WorkflowEvent.push
+
+    @cached_property
+    def event_actor(self) -> str | None:
+        """Returns the GitHub login of the user that triggered the workflow run."""
+        return self.github_context.get("actor")
+
+    @cached_property
+    def event_sender_type(self) -> str | None:
+        """Returns the type of the user that triggered the workflow run."""
+        sender_type = self.github_context.get("event", {}).get("sender", {}).get("type")
+        if not sender_type:
+            return None
+        assert isinstance(sender_type, str)
+        return sender_type
+
+    @cached_property
+    def is_bot(self) -> bool:
+        """Returns ``True`` if the workflow was triggered by a bot or automated process.
+
+        This is useful to only run some jobs on human-triggered events. Or skip jobs
+        triggered by bots to avoid infinite loops.
+        """
+        if self.event_sender_type == "Bot" or self.event_actor in (
+            "dependabot[bot]",
+            "dependabot-preview[bot]",
+        ):
+            return True
+        return False
+
+    @cached_property
+    def commit_range(self) -> tuple[str | None, str] | None:
+        """Range of commits bundled within the triggering event.
+
+        A workflow run is triggered by a singular event, which might encapsulate one or
+        more commits. This means the workflow will only run once on the last commit,
+        even if multiple new commits where pushed.
+
+        This is annoying when we want to keep a carefully constructed commit history,
+        and want to run the workflow on each commit. The typical example is a pull
+        request that is merged upstream but we'd like to produce artifacts (builds,
+        packages, etc.) for each individual commit.
+
+        The default ``GITHUB_SHA`` environment variable is not enough as it only points
+        to the last commit. We need to inspect the commit history to find all new ones.
+        New commits needs to be fetched differently in ``push`` and ``pull_requests``
+        events.
+
+        .. seealso::
+            - https://stackoverflow.com/a/67204539
+            - https://stackoverflow.com/a/62953566
+            - https://stackoverflow.com/a/61861763
+
+        .. seealso::
+            Pull request events on GitHub are a bit complex, see: `The Many SHAs of a
+            GitHub Pull Request
+            <https://www.kenmuse.com/blog/the-many-shas-of-a-github-pull-request/>`_.
+
+        .. todo::
+            Refactor so we can get rid of ``self.github_context``. Maybe there's enough
+            metadata lying around in the environment variables that we can inspect the
+            git history and find the commit range.
+        """
+        if not self.github_context or not self.event_type:
+            return None
+        # Pull request event.
+        if self.event_type in (
+            WorkflowEvent.pull_request,
+            WorkflowEvent.pull_request_target,
+        ):
+            base_ref = os.environ["GITHUB_BASE_REF"]
+            assert base_ref
+            assert (
+                self.github_context["event"]["pull_request"]["base"]["ref"] == base_ref
+            )
+            base_ref_sha = self.github_context["event"]["pull_request"]["base"]["sha"]
+            start = base_ref_sha
+            # We need to checkout the HEAD commit instead of the artificial merge
+            # commit introduced by the pull request.
+            end = self.github_context["event"]["pull_request"]["head"]["sha"]
+        # Push event.
+        else:
+            start = self.github_context["event"].get("before")
+            end = os.environ["GITHUB_SHA"]
+            assert end
+        logging.debug(f"Commit range: {start} -> {end}")
+        return start, end
+
+    @cached_property
+    def current_commit(self) -> Commit | None:
+        """Returns the current ``Commit`` object."""
+        return next(Repository(".", single="HEAD").traverse_commits())
+
+    @cached_property
+    def current_commit_matrix(self) -> Matrix | None:
+        """Pre-computed matrix with long and short SHA values of the current commit."""
+        return self.commit_matrix((self.current_commit,))
+
+    @cached_property
+    def new_commits(self) -> tuple[Commit, ...] | None:
+        """Returns list of ``Commit`` objects bundled within the triggering event."""
+        if not self.commit_range:
+            return None
+        start, end = self.commit_range
+
+        # Sanity check: make sure the start commit exists in the repository.
+        # XXX Even if we skip the start commit later on (because the range is
+        # inclusive), we still need to make sure it exists: PyDriller stills needs to
+        # find it to be able to traverse the commit history.
+        for commit_id in (start, end):
+            if not commit_id:
+                continue
+
+            if not self.git_deepen(commit_id):
+                logging.warning(
+                    "Skipping metadata extraction of the range of new commits."
+                )
+                return None
+
+        if not start:
+            logging.warning("No start commit found. Only one commit in range.")
+            assert end
+            return (self.git.get_commit(end),)
+
+        commit_list = []
+        for index, commit in enumerate(
+            Repository(".", from_commit=start, to_commit=end).traverse_commits()
+        ):
+            # Skip the first commit because the commit range is inclusive.
+            if index == 0:
+                continue
+            commit_list.append(commit)
+        return tuple(commit_list)
+
+    @cached_property
+    def new_commits_matrix(self) -> Matrix | None:
+        """Pre-computed matrix with long and short SHA values of new commits."""
+        return self.commit_matrix(self.new_commits)
+
+    @cached_property
+    def new_commits_hash(self) -> tuple[str, ...] | None:
+        """List all hashes of new commits."""
+        return self.new_commits_matrix["commit"] if self.new_commits_matrix else None
+
+    @cached_property
+    def release_commits(self) -> tuple[Commit, ...] | None:
+        """Returns list of ``Commit`` objects to be tagged within the triggering event.
+
+        We cannot identify a release commit based the presence of a ``vX.Y.Z`` tag
+        alone. That's because it is not present in the ``prepare-release`` pull request
+        produced by the ``changelog.yaml`` workflow. The tag is produced later on by
+        the ``release.yaml`` workflow, when the pull request is merged to ``main``.
+
+        Our best second option is to identify a release based on the full commit
+        message, based on the template used in the ``changelog.yaml`` workflow.
+        """
+        if not self.new_commits:
+            return None
+        return tuple(
+            commit
+            for commit in self.new_commits
+            if re.fullmatch(
+                r"^\[changelog\] Release v[0-9]+\.[0-9]+\.[0-9]+$",
+                commit.msg,
+            )
+        )
+
+    @cached_property
+    def release_commits_matrix(self) -> Matrix | None:
+        """Pre-computed matrix with long and short SHA values of release commits."""
+        return self.commit_matrix(self.release_commits)
+
+    @cached_property
+    def release_commits_hash(self) -> tuple[str, ...] | None:
+        """List all hashes of release commits."""
+        return (
+            self.release_commits_matrix["commit"]
+            if self.release_commits_matrix
+            else None
+        )
+
+    @cached_property
+    def mailmap_exists(self) -> bool:
+        return MAILMAP_PATH.is_file()
+
+    @cached_property
+    def gitignore_exists(self) -> bool:
+        return GITIGNORE_PATH.is_file()
+
+    @cached_property
+    def gitignore_parser(self) -> Parser | None:
+        """Returns a parser for the ``.gitignore`` file, if it exists."""
+        if self.gitignore_exists:
+            logging.debug(f"Parse {GITIGNORE_PATH}")
+            return get_parser_from_file(GITIGNORE_PATH)
+        return None
+
+    def gitignore_match(self, file_path: Path | str) -> bool:
+        if self.gitignore_parser and self.gitignore_parser.match(file_path):
+            return True
+        return False
+
+    def glob_files(self, *patterns: str) -> list[Path]:
+        """Return all file path matching the ``patterns``.
+
+        Patterns are glob patterns supporting ``**`` for recursive search, and ``!``
+        for negation.
+
+        All directories are traversed, whether they are hidden (i.e. starting with a
+        dot ``.``) or not, including symlinks.
+
+        Skips:
+
+        - files which does not exists
+        - directories
+        - broken symlinks
+        - files matching patterns specified by ``.gitignore`` file
+
+        Returns both hidden and non-hidden files.
+
+        All files are normalized to their absolute path, so that duplicates produced by
+        symlinks are ignored.
+
+        File path are returned as relative to the current working directory if
+        possible, or as absolute path otherwise.
+
+        The resulting list of file paths is sorted.
+        """
+        current_dir = Path.cwd()
+        seen = set()
+
+        for file_path in iglob(
+            patterns,
+            flags=NODIR | GLOBSTAR | DOTGLOB | GLOBTILDE | BRACE | FOLLOW | NEGATE,
+        ):
+            # Normalize the path to avoid duplicates.
+            try:
+                absolute_path = Path(file_path).resolve(strict=True)
+            # Skip files that do not exists and broken symlinks.
+            except OSError:
+                logging.warning(f"Skip non-existing file / broken symlink: {file_path}")
+                continue
+
+            # Simplify the path by trying to make it relative to the current location.
+            normalized_path = absolute_path
+            try:
+                normalized_path = absolute_path.relative_to(current_dir)
+            except ValueError:
+                # If the file is not relative to the current directory, keep its
+                # absolute path.
+                logging.debug(
+                    f"{absolute_path} is not relative to {current_dir}. "
+                    "Keeping the path absolute."
+                )
+
+            if normalized_path in seen:
+                logging.debug(f"Skip duplicate file: {normalized_path}")
+                continue
+
+            # Skip files that are ignored by .gitignore.
+            if self.gitignore_match(file_path):
+                logging.debug(f"Skip file matching {GITIGNORE_PATH}: {file_path}")
+                continue
+
+            seen.add(normalized_path)
+        return sorted(seen)
+
+    @cached_property
+    def python_files(self) -> list[Path]:
+        """Returns a list of python files."""
+        return self.glob_files("**/*.{py,pyi,pyw,pyx,ipynb}")
+
+    @cached_property
+    def json_files(self) -> list[Path]:
+        """Returns a list of JSON files."""
+        return self.glob_files(
+            "**/*.{json,jsonc,json5}",
+            "**/.code-workspace",
+            "!**/package-lock.json",
+        )
+
+    @cached_property
+    def yaml_files(self) -> list[Path]:
+        """Returns a list of YAML files."""
+        return self.glob_files("**/*.{yaml,yml}")
+
+    @cached_property
+    def workflow_files(self) -> list[Path]:
+        """Returns a list of GitHub workflow files."""
+        return self.glob_files(".github/workflows/**/*.{yaml,yml}")
+
+    @cached_property
+    def doc_files(self) -> list[Path]:
+        """Returns a list of doc files."""
+        return self.glob_files(
+            "**/*.{markdown,mdown,mkdn,mdwn,mkd,md,mdtxt,mdtext,rst,tex}"
+        )
+
+    @cached_property
+    def markdown_files(self) -> list[Path]:
+        """Returns a list of Markdown files."""
+        return self.glob_files("**/*.{markdown,mdown,mkdn,mdwn,mkd,md,mdtxt,mdtext}")
+
+    @cached_property
+    def image_files(self) -> list[Path]:
+        """Returns a list of image files.
+
+        Inspired by the list of image extensions supported by calibre's image-actions:
+        https://github.com/calibreapp/image-actions/blob/f325757/src/constants.ts#L32
+        """
+        return self.glob_files("**/*.{jpeg,jpg,png,webp,avif}")
+
+    @cached_property
+    def zsh_files(self) -> list[Path]:
+        """Returns a list of Zsh files."""
+        return self.glob_files("**/*.{sh,zsh}", "**/.{zshrc,zprofile,zshenv,zlogin}")
+
+    @cached_property
+    def is_python_project(self):
+        """Returns ``True`` if repository is a Python project.
+
+        Presence of a ``pyproject.toml`` file that respects the standards is enough
+        to consider the project as a Python one.
+        """
+        return False if self.pyproject is None else True
+
+    @cached_property
+    def pyproject(self) -> StandardMetadata | None:
+        """Returns metadata stored in the ``pyproject.toml`` file.
+
+        Returns ``None`` if the ``pyproject.toml`` does not exists or does not respects
+        the PEP standards.
+
+        .. warning::
+            Some third-party apps have their configuration saved into
+            ``pyproject.toml`` file, but that does not means the project is a Python
+            one. For that, the ``pyproject.toml`` needs to respect the PEPs.
+        """
+        if self.pyproject_path.exists() and self.pyproject_path.is_file():
+            toml = tomllib.loads(self.pyproject_path.read_text(encoding="UTF-8"))
+            try:
+                metadata = StandardMetadata.from_pyproject(toml)
+                return metadata
+            except ConfigurationError:
+                pass
+
+        return None
+
+    @cached_property
+    def package_name(self) -> str | None:
+        """Returns package name as published on PyPi."""
+        if self.pyproject and self.pyproject.canonical_name:
+            return self.pyproject.canonical_name
+        return None
+
+    @cached_property
+    def script_entries(self) -> list[tuple[str, str, str]]:
+        """Returns a list of tuples containing the script name, its module and
+        callable.
+
+        Results are derived from the script entries of ``pyproject.toml``. So that:
+
+        .. code-block:: toml
+            [project.scripts]
+            mdedup = "mail_deduplicate.cli:mdedup"
+            mpm = "meta_package_manager.__main__:main"
+
+        Will yields the following list:
+
+        .. code-block:: python
+            (
+                ("mdedup", "mail_deduplicate.cli", "mdedup"),
+                ("mpm", "meta_package_manager.__main__", "main"),
+                ...,
+            )
+        """
+        entries = []
+        if self.pyproject:
+            for cli_id, script in self.pyproject.scripts.items():
+                module_id, callable_id = script.split(":")
+                entries.append((cli_id, module_id, callable_id))
+        # Double check we do not have duplicate entries.
+        all_cli_ids = [cli_id for cli_id, _, _ in entries]
+        assert len(set(all_cli_ids)) == len(all_cli_ids)
+        return entries
+
+    @cached_property
+    def py_target_versions(self) -> tuple[Version, ...] | None:
+        """Generates the list of Python target versions.
+
+        Only takes ``major.minor`` variations into account. Smaller version dimensions
+        are ignored, so a package depending on ``3.8.6`` will keep ``3.8`` as a Python
+        target.
+        """
+        if self.pyproject and self.pyproject.requires_python:
+            # Dumb down specifiers' lower bounds to their major.minor version.
+            spec_list = []
+            for spec in self.pyproject.requires_python:
+                if spec.operator in (">=", ">"):
+                    release = Version(spec.version).release
+                    new_spec = f"{spec.operator}{release[0]}.{release[1]}"
+                else:
+                    new_spec = str(spec)
+                spec_list.append(new_spec)
+            relaxed_specs = SpecifierSet(",".join(spec_list))
+            logging.debug(
+                "Relax Python requirements from "
+                f"{self.pyproject.requires_python} to {relaxed_specs}."
+            )
+
+            # Iterate through Python version support.
+            return tuple(
+                Version(target)
+                for target in tuple(TargetVersion)
+                if relaxed_specs.contains(target)
+            )
+        return None
+
+    @cached_property
+    def blacken_docs_params(self) -> str | None:
+        """Generates ``blacken-docs`` parameters.
+
+        `Blacken-docs reuses Black's --target-version pyXY parameters
+        <https://github.com/adamchainz/blacken-docs/blob/cd4e60f/src/blacken_docs/__init__.py#L263-L271>`_,
+        and needs to be fed with a subset of these:
+        - ``--target-version py33``
+        - ``--target-version py34``
+        - ``--target-version py35``
+        - ``--target-version py36``
+        - ``--target-version py37``
+        - ``--target-version py38``
+        - ``--target-version py39``
+        - ``--target-version py310``
+        - ``--target-version py311``
+        - ``--target-version py312``
+        - ``--target-version py313``
+        - ``--target-version py314``
+
+        As mentioned in Black usage, you should `include all Python versions that you
+        want your code to run under
+        <https://github.com/psf/black/issues/751#issuecomment-473066811>`_.
+        """
+        if self.py_target_versions:
+            return " ".join(
+                f"--target-version py{version.major}{version.minor}"
+                for version in self.py_target_versions
+            )
+        return None
+
+    @cached_property
+    def mypy_params(self) -> str | None:
+        """Generates `mypy` parameters.
+
+        Mypy needs to be fed with this parameter: ``--python-version 3.x``.
+        """
+        if self.py_target_versions:
+            # Compare to Mypy's lowest supported version of Python dialect.
+            major, minor = max(
+                MYPY_VERSION_MIN,
+                min((v.major, v.minor) for v in self.py_target_versions),
+            )
+            return f"--python-version {major}.{minor}"
+        return None
+
+    @staticmethod
+    def get_current_version() -> str | None:
+        """Returns the current version as managed by bump-my-version.
+
+        Same as calling the CLI:
+
+            .. code-block:: shell-session
+                $ bump-my-version show current_version
+        """
+        conf_file = find_config_file()
+        if not conf_file:
+            return None
+        config = get_configuration(conf_file)
+        config_dict = config.model_dump()
+        return str(resolve_name(config_dict, "current_version"))
+
+    @cached_property
+    def current_version(self) -> str | None:
+        """Returns the current version.
+
+        Current version is fetched from the ``bump-my-version`` configuration file.
+
+        During a release we get two commits bundled into a single event. The first one
+        is the release commit itself freezing the version to the release number. The
+        second one is the commit that bumps the version to the next one. In this
+        situation, the current version returned is the one from the most recent commit.
+        """
+        version = None
+        if self.new_commits_matrix:
+            details = self.new_commits_matrix.include
+            if details:
+                version = details[0].get("current_version")
+        else:
+            version = self.get_current_version()
+        return version
+
+    @cached_property
+    def released_version(self) -> str | None:
+        """Returns the version of the release commit."""
+        version = None
+        if self.release_commits_matrix:
+            details = self.release_commits_matrix.include
+            if details:
+                # This script is only designed for at most 1 release in the list of new
+                # commits.
+                assert len(details) == 1
+                version = details[0].get("current_version")
+        return version
+
+    @cached_property
+    def is_sphinx(self) -> bool:
+        """Returns ``True`` if the Sphinx config file is present."""
+        # The Sphinx config file is present, that's enough for us.
+        return self.sphinx_conf_path.exists() and self.sphinx_conf_path.is_file()
+
+    @cached_property
+    def active_autodoc(self) -> bool:
+        """Returns ``True`` if there are active Sphinx extensions."""
+        if self.is_sphinx:
+            # Look for list of active Sphinx extensions.
+            for node in ast.parse(self.sphinx_conf_path.read_bytes()).body:
+                if isinstance(node, ast.Assign) and isinstance(
+                    node.value, ast.List | ast.Tuple
+                ):
+                    extension_found = "extensions" in (
+                        t.id  # type: ignore[attr-defined]
+                        for t in node.targets
+                    )
+                    if extension_found:
+                        elements = (
+                            e.value
+                            for e in node.value.elts
+                            if isinstance(e, ast.Constant)
+                        )
+                        if "sphinx.ext.autodoc" in elements:
+                            return True
+        return False
+
+    @cached_property
+    def nuitka_matrix(self) -> Matrix | None:
+        """Pre-compute a matrix for Nuitka compilation workflows.
+
+        Combine the variations of:
+        - all new commits
+        - all entry points
+        - for the 3 main OSes
+        - for a set of architectures
+
+        Returns a ready-to-use matrix structure, where each variation is augmented with
+        specific extra parameters by the way of matching parameters in the `include`
+        directive.
+
+        .. code-block:: python
+            {
+                "os": [
+                    "ubuntu-24.04-arm",
+                    "ubuntu-slim",
+                    "macos-26",
+                    "macos-15-intel",
+                    "windows-11-arm",
+                    "windows-2025",
+                ],
+                "entry_point": [
+                    "mpm",
+                ],
+                "commit": [
+                    "346ce664f055fbd042a25ee0b7e96702e95",
+                    "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                ],
+                "include": [
+                    {
+                        "target": "linux-arm64",
+                        "os": "ubuntu-24.04-arm",
+                        "platform_id": "linux",
+                        "arch": "arm64",
+                        "extension": "bin",
+                    },
+                    {
+                        "target": "linux-x64",
+                        "os": "ubuntu-slim",
+                        "platform_id": "linux",
+                        "arch": "x64",
+                        "extension": "bin",
+                    },
+                    {
+                        "target": "macos-arm64",
+                        "os": "macos-26",
+                        "platform_id": "macos",
+                        "arch": "arm64",
+                        "extension": "bin",
+                    },
+                    {
+                        "target": "macos-x64",
+                        "os": "macos-15-intel",
+                        "platform_id": "macos",
+                        "arch": "x64",
+                        "extension": "bin",
+                    },
+                    {
+                        "target": "windows-arm64",
+                        "os": "windows-11-arm",
+                        "platform_id": "windows",
+                        "arch": "arm64",
+                        "extension": "exe",
+                    },
+                    {
+                        "target": "windows-x64",
+                        "os": "windows-2025",
+                        "platform_id": "windows",
+                        "arch": "x64",
+                        "extension": "exe",
+                    },
+                    {
+                        "entry_point": "mpm",
+                        "cli_id": "mpm",
+                        "module_id": "meta_package_manager.__main__",
+                        "callable_id": "main",
+                        "module_path": "meta_package_manager/__main__.py",
+                    },
+                    {
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "short_sha": "346ce66",
+                        "current_version": "2.0.0",
+                    },
+                    {
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "short_sha": "6f27db4",
+                        "current_version": "1.9.1",
+                    },
+                    {
+                        "os": "ubuntu-24.04-arm",
+                        "entry_point": "mpm",
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "bin_name": "mpm-linux-arm64-346ce66.bin",
+                    },
+                    {
+                        "os": "ubuntu-24.04-arm",
+                        "entry_point": "mpm",
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "bin_name": "mpm-linux-arm64-6f27db4.bin",
+                    },
+                    {
+                        "os": "ubuntu-slim",
+                        "entry_point": "mpm",
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "bin_name": "mpm-linux-x64-346ce66.bin",
+                    },
+                    {
+                        "os": "ubuntu-slim",
+                        "entry_point": "mpm",
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "bin_name": "mpm-linux-x64-6f27db4.bin",
+                    },
+                    {
+                        "os": "macos-26",
+                        "entry_point": "mpm",
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "bin_name": "mpm-macos-arm64-346ce66.bin",
+                    },
+                    {
+                        "os": "macos-26",
+                        "entry_point": "mpm",
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "bin_name": "mpm-macos-arm64-6f27db4.bin",
+                    },
+                    {
+                        "os": "macos-15-intel",
+                        "entry_point": "mpm",
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "bin_name": "mpm-macos-x64-346ce66.bin",
+                    },
+                    {
+                        "os": "macos-15-intel",
+                        "entry_point": "mpm",
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "bin_name": "mpm-macos-x64-6f27db4.bin",
+                    },
+                    {
+                        "os": "windows-11-arm",
+                        "entry_point": "mpm",
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "bin_name": "mpm-windows-arm64-346ce66.bin",
+                    },
+                    {
+                        "os": "windows-11-arm",
+                        "entry_point": "mpm",
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "bin_name": "mpm-windows-arm64-6f27db4.bin",
+                    },
+                    {
+                        "os": "windows-2025",
+                        "entry_point": "mpm",
+                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
+                        "bin_name": "mpm-windows-x64-346ce66.exe",
+                    },
+                    {
+                        "os": "windows-2025",
+                        "entry_point": "mpm",
+                        "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
+                        "bin_name": "mpm-windows-x64-6f27db4.exe",
+                    },
+                    {
+                        "state": "stable",
+                    },
+                ],
+            }
+        """
+        # Only produce a matrix if the project is providing CLI entry points.
+        if not self.script_entries:
+            return None
+
+        matrix = Matrix()
+
+        # Register all runners on which we want to run Nuitka builds.
+        matrix.add_variation(
+            "os", tuple(map(itemgetter("os"), NUITKA_BUILD_TARGETS.values()))
+        )
+        # Augment each "os" entry with platform-specific data.
+        for target_data in FLAT_BUILD_TARGETS:
+            matrix.add_includes(target_data)
+
+        # Augment each entry point with some metadata.
+        for cli_id, module_id, callable_id in self.script_entries:
+            # CLI ID is supposed to be unique, we'll use that as a key.
+            matrix.add_variation("entry_point", [cli_id])
+            # Derive CLI module path from its ID.
+            # XXX We consider here the module is directly callable, because Nuitka
+            # doesn't seems to support the entry-point notation.
+            module_path = Path(f"{module_id.replace('.', '/')}.py")
+            assert module_path.exists()
+            matrix.add_includes({
+                "entry_point": cli_id,
+                "cli_id": cli_id,
+                "module_id": module_id,
+                "callable_id": callable_id,
+                "module_path": str(module_path),
+            })
+
+        # We'd like to run a build for each new commit bundled in the action trigger.
+        # If no new commits are detected, it's because we are not in a GitHub workflow
+        # event, so we'll fallback to the current commit and only build for it.
+        build_commit_matrix = (
+            self.new_commits_matrix
+            if self.new_commits_matrix
+            else self.current_commit_matrix
+        )
+        assert build_commit_matrix
+        # Extend the matrix with a new dimension: a list of commits.
+        matrix.add_variation("commit", build_commit_matrix["commit"])
+        matrix.add_includes(*build_commit_matrix.include)
+
+        # Augment each variation set of the matrix with a the binary name to be
+        # produced by Nuitka. Itererate over all matrix variation sets so we have all
+        # metadata necessary to generate a unique name specific to these variations.
+        for variations in matrix.solve():
+            # We will re-attach back this binary name to the with an include directive,
+            # so we need a copy the main variants it corresponds to.
+            bin_name_include = {k: variations[k] for k in matrix.variations}
+            bin_name_include["bin_name"] = (
+                "{cli_id}-{target}-{short_sha}.{extension}"
+            ).format(**variations)
+            matrix.add_includes(bin_name_include)
+
+        # All jobs are stable by default, unless marked otherwise by specific
+        # configuration.
+        matrix.add_includes({"state": "stable"})
+        for unstable_target in self.unstable_targets:
+            matrix.add_includes({
+                "state": "unstable",
+                "os": NUITKA_BUILD_TARGETS[unstable_target]["os"],
+            })
+
+        return matrix
+
+    @cached_property
+    def release_notes(self) -> str | None:
+        """Generate notes to be attached to the GitHub release."""
+        # Produce the release notes of the release version or the current one.
+        version = self.released_version
+        if not version:
+            version = self.current_version
+        if not version:
+            return None
+
+        # Extract the changelog entry corresponding to the release version, and located
+        # between the first two `##` second-level markdown titles.
+        changes = ""
+        match = re.search(
+            rf"^##(?P<title>.+{escape(version)} .+?)\n(?P<changes>.*?)\n##",
+            Path("./changelog.md").read_text(encoding="UTF-8"),
+            flags=re.MULTILINE | re.DOTALL,
+        )
+        if match:
+            changes = match.groupdict().get("changes", "").strip()
+            # Add a title.
+            if changes:
+                changes = "### Changes\n\n" + changes
+
+        # Generate a link to the version of the package published on PyPi.
+        pypi_link = ""
+        if self.package_name:
+            pypi_link = (
+                "[🐍 Available on PyPi](https://pypi.org/project/"
+                + self.package_name
+                + "/"
+                + version
+                + ")."
+            )
+
+        # Assemble the release notes.
+        return f"{changes}\n\n{pypi_link}".strip()
+
+    @staticmethod
+    def format_github_value(value: Any) -> str:
+        """Transform Python value to GitHub-friendly, JSON-like, console string.
+
+        Renders:
+        - `str` as-is
+        - `None` into empty string
+        - `bool` into lower-cased string
+        - `Matrix` into JSON string
+        - `Iterable` of mixed strings and `Path` into a serialized space-separated
+          string, where `Path` items are double-quoted
+        - other `Iterable` into a JSON string
+        """
+        # Structured metadata to be rendered as JSON.
+        if isinstance(value, Matrix):
+            return str(value)
+
+        # Convert non-strings.
+        if not isinstance(value, str):
+            if value is None:
+                value = ""
+
+            elif isinstance(value, bool):
+                value = str(value).lower()
+
+            elif isinstance(value, dict):
+                raise NotImplementedError
+
+            elif isinstance(value, Iterable):
+                # Cast all items to strings, wrapping Path items with double-quotes.
+                if all(isinstance(i, (str, Path)) for i in value):
+                    items = (
+                        (f'"{i}"' if isinstance(i, Path) else str(i)) for i in value
+                    )
+                    value = " ".join(items)
+                # XXX We only support iterables of dict[str, str] for now.
+                else:
+                    assert all(
+                        isinstance(i, dict)
+                        and all(
+                            isinstance(k, str) and isinstance(v, str)
+                            for k, v in i.items()
+                        )
+                        for i in value
+                    ), f"Unsupported iterable value: {value!r}"
+                    value = json.dumps(value)
+
+            else:
+                raise NotImplementedError(f"GitHub formatting for: {value!r}")
+
+        return str(value)
+
+    def dump(self, dialect: Dialect = Dialect.github) -> str:
+        """Returns all metadata in the specified format.
+
+        Defaults to GitHub dialect.
+        """
+        metadata: dict[str, Any] = {
+            "is_bot": self.is_bot,
+            "new_commits": self.new_commits_hash,
+            "release_commits": self.release_commits_hash,
+            "mailmap_exists": self.mailmap_exists,
+            "gitignore_exists": self.gitignore_exists,
+            "python_files": self.python_files,
+            "json_files": self.json_files,
+            "yaml_files": self.yaml_files,
+            "workflow_files": self.workflow_files,
+            "doc_files": self.doc_files,
+            "markdown_files": self.markdown_files,
+            "image_files": self.image_files,
+            "zsh_files": self.zsh_files,
+            "is_python_project": self.is_python_project,
+            "package_name": self.package_name,
+            "blacken_docs_params": self.blacken_docs_params,
+            "mypy_params": self.mypy_params,
+            "current_version": self.current_version,
+            "released_version": self.released_version,
+            "is_sphinx": self.is_sphinx,
+            "active_autodoc": self.active_autodoc,
+            "release_notes": self.release_notes,
+            "new_commits_matrix": self.new_commits_matrix,
+            "release_commits_matrix": self.release_commits_matrix,
+            "build_targets": FLAT_BUILD_TARGETS,
+            "nuitka_matrix": self.nuitka_matrix,
+        }
+
+        logging.debug(f"Raw metadata: {metadata!r}")
+        logging.debug(f"Format metadata into {dialect} format.")
+
+        content = ""
+        if dialect == Dialect.github:
+            for env_name, value in metadata.items():
+                env_value = self.format_github_value(value)
+
+                is_multiline = bool(len(env_value.splitlines()) > 1)
+                if not is_multiline:
+                    content += f"{env_name}={env_value}\n"
+                else:
+                    # Use a random unique delimiter to encode multiline value:
+                    delimiter = f"GHA_DELIMITER_{randint(10**8, (10**9) - 1)}"
+                    content += f"{env_name}<<{delimiter}\n{env_value}\n{delimiter}\n"
+        else:
+            assert dialect == Dialect.json
+            content = json.dumps(metadata, cls=JSONMetadata, indent=2)
+
+        logging.debug(f"Formatted metadata:\n{content}")
+
+        return content