From be7e1eeeedf43d170d93bd72d6032203e4ab4e99 Mon Sep 17 00:00:00 2001
From: Kevin Veen-Birkenbach <kevin@veen.world>
Date: Wed, 29 Jul 2026 21:24:23 +0200
Subject: [PATCH] refactor(ci): resolve the dev-runtime matrix through a named
 module

The workspace workflow asked the distro SPOT two questions through embedded python one-liners: the matrix image list, and the distro behind a matrix entry. Give both a name -- distro_of_dev_runtime_image() as the counterpart to dev_runtime_image(), and a cli.meta.ci.dev_runtime module shaped like its image_ref neighbour. The empty-SPOT guard that protected the matrix from silently skipping every job moves along with it. No caller yet; the workflow switches over in the next commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 cli/meta/ci/dev_runtime.py       | 52 ++++++++++++++++++++++++++++++++
 tests/unit/utils/test_distros.py |  9 ++++++
 utils/distros.py                 | 13 +++++++-
 3 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 cli/meta/ci/dev_runtime.py

diff --git a/cli/meta/ci/dev_runtime.py b/cli/meta/ci/dev_runtime.py
new file mode 100644
index 0000000000..59bb021002
--- /dev/null
+++ b/cli/meta/ci/dev_runtime.py
@@ -0,0 +1,52 @@
+"""Answer the development-runtime matrix questions from the distro SPOT.
+
+Exists so workflow steps can ask for the matrix, and for the distro behind a
+matrix entry, without embedding a python one-liner per question.
+
+    python3 -m cli.meta.ci.dev_runtime images
+    python3 -m cli.meta.ci.dev_runtime distro --image fedora:latest
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from utils.distros import (
+    FILE_META_DISTROS,
+    dev_runtime_images,
+    distro_of_dev_runtime_image,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("images", help="Print the matrix images as a JSON array.")
+    distro = commands.add_parser(
+        "distro", help="Print the distro a matrix image belongs to."
+    )
+    distro.add_argument(
+        "--image", required=True, help="Matrix image, e.g. fedora:latest."
+    )
+    args = parser.parse_args(argv)
+
+    if args.command == "images":
+        images = list(dev_runtime_images())
+        if not images:
+            print(
+                f"{FILE_META_DISTROS} declares no dev runtime image; "
+                "an empty matrix would skip every workspace job silently",
+                file=sys.stderr,
+            )
+            return 1
+        print(json.dumps(images))
+        return 0
+
+    print(distro_of_dev_runtime_image(args.image))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tests/unit/utils/test_distros.py b/tests/unit/utils/test_distros.py
index 6a758477a2..2bb7a77a85 100644
--- a/tests/unit/utils/test_distros.py
+++ b/tests/unit/utils/test_distros.py
@@ -10,6 +10,7 @@ from utils.distros import (
     dev_runtime_images,
     distro_family,
     distro_names,
+    distro_of_dev_runtime_image,
     environment_image,
     galaxy_platforms,
     pkgmgr_image,
@@ -65,6 +66,14 @@ class TestDistroSpot(unittest.TestCase):
         with self.assertRaises(UnknownDistroError):
             pkgmgr_image("gentoo", owner="acme", tag="stable")
 
+    def test_dev_runtime_image_round_trips_to_its_distro(self) -> None:
+        for name in distro_names():
+            self.assertEqual(distro_of_dev_runtime_image(dev_runtime_image(name)), name)
+
+    def test_unknown_dev_runtime_image_is_rejected(self) -> None:
+        with self.assertRaises(UnknownDistroError):
+            distro_of_dev_runtime_image("gentoo:latest")
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/utils/distros.py b/utils/distros.py
index a96f025327..c03e33d947 100644
--- a/utils/distros.py
+++ b/utils/distros.py
@@ -36,7 +36,7 @@ IMAGE_ENVIRONMENT = "environment"
 
 
 class UnknownDistroError(ValueError):
-    """Raised for a distro id that ``meta/distros.yml`` does not declare."""
+    """Raised for a distro id or image that ``meta/distros.yml`` does not declare."""
 
 
 def _doc() -> dict:
@@ -90,6 +90,17 @@ def dev_runtime_image(distro: str) -> str:
     return _spec(distro)["dev_runtime_image"]
 
 
+def distro_of_dev_runtime_image(image: str) -> str:
+    """Distro id whose development environment boots from ``image``."""
+    for name, spec in _specs().items():
+        if spec["dev_runtime_image"] == image:
+            return name
+    raise UnknownDistroError(
+        f"{image!r} is not a dev_runtime_image in {FILE_META_DISTROS}. "
+        f"Declared: {', '.join(dev_runtime_images())}."
+    )
+
+
 def image_template(kind: str) -> str:
     """Raw reference template, for callers rendering a non-distro slug.