# 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-24.04",
        "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-24.04",
        "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-24.04",
            "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-24.04",
            "entry_point": "mpm",
            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
            "bin_name": "mpm-linux-x64-346ce66.bin"
        },
        {
            "os": "ubuntu-24.04",
            "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-24.04",
        "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>`_.
"""


Dialects = StrEnum("Dialects", ("github", "json"))
"""Dialects 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
            )
            full_base_ref = f"origin/{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-24.04",
                    "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-24.04",
                        "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-24.04",
                        "entry_point": "mpm",
                        "commit": "346ce664f055fbd042a25ee0b7e96702e95",
                        "bin_name": "mpm-linux-x64-346ce66.bin",
                    },
                    {
                        "os": "ubuntu-24.04",
                        "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: Dialects = Dialects.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 == Dialects.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 == Dialects.json
            content = json.dumps(metadata, cls=JSONMetadata, indent=2)

        logging.debug(f"Formatted metadata:\n{content}")

        return content
