bugs: prefer the version due for stabilization under --filter-stablereqs

A dependency pulled into the graph also goes thought the stablereq check,
and if several versions of a package would do, the one the check considers
due for stabilization is preferred, so a dependency pulled into the graph
lands on the version actually waiting rather than an older one.

It stays a preference: a version which is masked, live, or dropped from the
candidates falls through to the previous choice, so the run is never left
with nothing to file.

Signed-off-by: Arthur Zamarin <arthurzam@gentoo.org>

Author: arthurzam

NEWS.rst

@@ -19,6 +19,10 @@ pkgdev 0.2.18 (unreleased)
 - bugs: fix ``--filter-stablereqs`` collapsing a target which matches several
   packages down to a single one (Arthur Zamarin)
 
+- bugs: under ``--filter-stablereqs``, when pulling dependency, prefer the
+  version the stablereq check considers due for stabilization if possible
+  (Arthur Zamarin)
+
 pkgdev 0.2.17 (2026-08-14)
 --------------------------
 

src/pkgdev/scripts/pkgdev_bugs.py

@@ -476,11 +476,25 @@ def __init__(self, out: Formatter, err: Formatter, options):
         self.added_repo = git_addon.cached_repo(GitAddedRepo)
         self.modified_repo = git_addon.cached_repo(GitModifiedRepo)
         self.stablereq_check = stablereq.StableRequestCheck(self.options, git_addon=git_addon)
+        self._stablereq_due: dict[str, tuple[str, ...]] = {}
 
     def mk_fake_pkg(self, pkg: package, keywords: set[str], stable: bool = True):
         kws = tuple(keywords) if stable else tuple(f"~{kw}" for kw in keywords)
         return MutatedPkg(pkg, {"keywords": kws})
 
+    def stablereq_versions(self, unversioned: atom) -> tuple[str, ...]:
+        """The versions of a package the stablereq check flags as due."""
+        if (due := self._stablereq_due.get(unversioned.key)) is None:
+            # the check reads every version, to tell which of them are stable
+            pkgset = self.options.search_repo.match(unversioned)
+            due = tuple(
+                f"{res.category}/{res.package}-{res.version}"
+                for res in self.stablereq_check.feed(sorted(pkgset))
+                if isinstance(res, stablereq.StableRequest)
+            )
+            self._stablereq_due[unversioned.key] = due
+        return due
+
     def find_best_match(self, restrict, pkgset: list[package], prefer_semi_stable=True) -> package:
         restrict = boolean.AndRestriction(
             *restrict,
@@ -495,6 +509,12 @@ def find_best_match(self, restrict, pkgset: list[package], prefer_semi_stable=Tr
         if intersect := tuple(filter(restrict.match, all_pkgs)):
             return max(intersect)
         matches = sorted(filter(restrict.match, pkgset), reverse=True)
+        # prefer the version the stablereq check considers due for stabilization
+        if self.options.filter_stablereqs and len(matches) > 1:
+            by_cpv = {match.versioned_atom.cpvstr: match for match in matches}
+            for cpvstr in self.stablereq_versions(matches[0].unversioned_atom):
+                if match := by_cpv.get(cpvstr):
+                    return match
         # prefer package with any stable keyword
         if prefer_semi_stable:
             for match in matches:

tests/scripts/test_pkgdev_bugs.py

@@ -142,7 +142,9 @@ def test_keywordreq(self, repo):
 def mk_graph(repo, category=BugCategory.STABLEREQ):
     # build a DependencyGraph without running its heavy __init__
     graph = bugs.DependencyGraph.__new__(bugs.DependencyGraph)
-    graph.options = SimpleNamespace(repo=repo, search_repo=repo, category=category)
+    graph.options = SimpleNamespace(
+        repo=repo, search_repo=repo, category=category, filter_stablereqs=False
+    )
     graph.out = SimpleNamespace(
         write=lambda *a, **k: None, warn=lambda *a, **k: None, flush=lambda: None
     )
@@ -151,6 +153,8 @@ def mk_graph(repo, category=BugCategory.STABLEREQ):
     graph.starting_nodes = set()
     graph.targets = ()
     graph.target_arches = {}
+    graph.stablereq_check = SimpleNamespace(feed=lambda pkgs: iter(()))
+    graph._stablereq_due = {}
     return graph
 
 
@@ -648,3 +652,123 @@ def test_single_package_target_is_unchanged(self, repo):
         graph, _ = self.mk_stablereq_graph(repo, {"cat/a-2"})
         graph.load_targets([(None, parserestrict.parse_match("cat/a"), frozenset())])
         assert [str(pkg.versioned_atom) for pkg in graph.targets] == ["=cat/a-2"]
+
+
+STABLE_THEN_UNSTABLE = {
+    "1": {"KEYWORDS": ["amd64"]},
+    "2": {"KEYWORDS": ["~amd64"]},
+    "3": {"KEYWORDS": ["~amd64"]},
+}
+
+
+class TestFindBestMatch:
+    """Each step of the preference chain deciding which version gets filed."""
+
+    def mk(self, repo, versions=None, masks=(), due=()):
+        for ver, kwargs in (versions or STABLE_THEN_UNSTABLE).items():
+            repo.create_ebuild(f"cat/dep-{ver}", **kwargs)
+        if masks:
+            with open(pjoin(repo.location, "profiles", "package.mask"), "w") as f:
+                f.write("\n".join(masks) + "\n")
+        repo.sync()
+
+        graph = mk_graph(repo)
+        if due:
+
+            def feed(pkgs):
+                for pkg in pkgs:
+                    if pkg.versioned_atom.cpvstr in due:
+                        yield bugs.stablereq.StableRequest(
+                            slot=pkg.slot, keywords=pkg.keywords, age=40, pkg=pkg
+                        )
+
+            graph.stablereq_check = SimpleNamespace(feed=feed)
+            graph.options.filter_stablereqs = True
+        return graph, repo.match(atom("cat/dep"))
+
+    @staticmethod
+    def pick(graph, pkgset, **kwargs):
+        return str(graph.find_best_match([atom("cat/dep")], pkgset, **kwargs).versioned_atom)
+
+    @staticmethod
+    def version(pkgset, fullver):
+        return next(pkg for pkg in pkgset if pkg.fullver == fullver)
+
+    def test_a_user_selected_target_wins(self, repo):
+        graph, pkgset = self.mk(repo)
+        graph.targets = (self.version(pkgset, "2"),)
+        assert self.pick(graph, pkgset) == "=cat/dep-2"
+
+    def test_the_newest_user_selected_target_wins(self, repo):
+        graph, pkgset = self.mk(repo)
+        graph.targets = (self.version(pkgset, "1"), self.version(pkgset, "2"))
+        assert self.pick(graph, pkgset) == "=cat/dep-2"
+
+    def test_a_package_already_in_the_graph_wins(self, repo):
+        graph, pkgset = self.mk(repo)
+        graph.nodes = {bugs.GraphNode(((self.version(pkgset, "2"), {"*"}),))}
+        assert self.pick(graph, pkgset) == "=cat/dep-2"
+
+    def test_a_user_target_beats_the_graph(self, repo):
+        graph, pkgset = self.mk(repo)
+        graph.targets = (self.version(pkgset, "1"),)
+        graph.nodes = {bugs.GraphNode(((self.version(pkgset, "3"), {"*"}),))}
+        assert self.pick(graph, pkgset) == "=cat/dep-1"
+
+    def test_the_stablereq_due_version_wins(self, repo):
+        graph, pkgset = self.mk(repo, due={"cat/dep-2"})
+        assert self.pick(graph, pkgset) == "=cat/dep-2"
+
+    def test_the_graph_beats_the_stablereq_due_version(self, repo):
+        graph, pkgset = self.mk(repo, due={"cat/dep-2"})
+        graph.nodes = {bugs.GraphNode(((self.version(pkgset, "3"), {"*"}),))}
+        assert self.pick(graph, pkgset) == "=cat/dep-3"
+
+    def test_the_stablereq_step_needs_filter_stablereqs(self, repo):
+        graph, pkgset = self.mk(repo, due={"cat/dep-2"})
+        graph.options.filter_stablereqs = False
+        assert self.pick(graph, pkgset) == "=cat/dep-1"
+
+    def test_a_due_version_outside_the_candidates_is_passed_over(self, repo):
+        graph, pkgset = self.mk(repo, due={"cat/dep-3"})
+        candidates = [pkg for pkg in pkgset if pkg.fullver != "3"]
+        assert self.pick(graph, candidates) == "=cat/dep-1"
+
+    def test_the_stablereq_answer_is_cached_per_package(self, repo):
+        graph, pkgset = self.mk(repo, due={"cat/dep-2"})
+        calls = []
+        inner = graph.stablereq_check.feed
+        graph.stablereq_check = SimpleNamespace(feed=lambda pkgs: (calls.append(1), inner(pkgs))[1])
+        self.pick(graph, pkgset)
+        self.pick(graph, pkgset)
+        assert len(calls) == 1
+
+    def test_a_semi_stable_version_beats_a_newer_unstable_one(self, repo):
+        graph, pkgset = self.mk(repo)
+        assert self.pick(graph, pkgset) == "=cat/dep-1"
+
+    def test_the_newest_wins_when_semi_stable_is_not_preferred(self, repo):
+        graph, pkgset = self.mk(repo)
+        assert self.pick(graph, pkgset, prefer_semi_stable=False) == "=cat/dep-3"
+
+    def test_versions_without_keywords_are_passed_over(self, repo):
+        versions = dict(STABLE_THEN_UNSTABLE, **{"3": {"KEYWORDS": []}})
+        graph, pkgset = self.mk(repo, versions)
+        assert self.pick(graph, pkgset, prefer_semi_stable=False) == "=cat/dep-2"
+
+    def test_the_newest_is_the_last_resort(self, repo):
+        versions = {ver: {"KEYWORDS": []} for ver in ("1", "2", "3")}
+        graph, pkgset = self.mk(repo, versions)
+        assert self.pick(graph, pkgset) == "=cat/dep-3"
+
+    def test_live_versions_are_excluded(self, repo):
+        # keyworded, so only the live filter can keep it out of the running
+        versions = dict(
+            STABLE_THEN_UNSTABLE, **{"9999": {"PROPERTIES": "live", "KEYWORDS": ["~amd64"]}}
+        )
+        graph, pkgset = self.mk(repo, versions)
+        assert self.pick(graph, pkgset, prefer_semi_stable=False) == "=cat/dep-3"
+
+    def test_masked_versions_are_excluded(self, repo):
+        graph, pkgset = self.mk(repo, masks=("=cat/dep-3",))
+        assert self.pick(graph, pkgset, prefer_semi_stable=False) == "=cat/dep-2"