docs+ci: clarify vinca's 3 exclusion mechanisms, add orphaned-patch check

vinca.yaml comments: packages_select_by_deps's if-wrapper (primary way
to exclude a package's own recipe), packages_skip_by_deps (transitive
pull-in only, does not stop direct selection), and
packages_remove_from_deps (a third, independent way to fully exclude a
package's own build via resolve_pkgname()/should_skip_pkg -- which also
inseparably strips it from other recipes' deps) are easy to conflate;
this came up repeatedly this session, including a mechanism that was
initially mis-explained. Verified against the vinca revision this repo
locks (pypi git+vinca lockfile entry).

check_orphaned_platform_patches.py replicates vinca's exact patch-glob +
add_package_name_variants() logic to catch a real bug class: a
platform-specific patch silently never wired into any recipe because
its filename uses a different name-prefix than another patch for the
same package (setdefault() in add_package_name_variants is a no-op once
either prefix already has its own entry) -- this is exactly what
orphaned ros-jazzy-sick-scan-xd.osx.patch for months on ros-jazzy.
Wired into `pixi run check-patches` via a new check-orphaned-patches
task dependency so it runs on every PR. Zero hits currently on humble.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Tobias-Fischer

check_orphaned_platform_patches.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""
+check_orphaned_platform_patches.py
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Detect patch files in ``patch/`` that vinca will silently never wire
+into any recipe's ``patches:`` list.
+
+Background
+----------
+vinca (see ``vinca/main.py`` around the ``patch_dir`` glob, and
+``vinca/utils.py::add_package_name_variants``) builds a dict keyed by
+the patch filename's prefix (everything before an optional
+``.osx``/``.win``/``.linux``/``.unix``/``.emscripten`` suffix), then
+cross-links name-prefix variants of the *same* logical package
+(``X`` <-> ``ros-X`` <-> ``ros2-X`` <-> ``ros-<distro>-X``) via
+``dict.setdefault()``.
+
+``setdefault`` only fills in a key that is still *absent*. If a
+package has a plain patch under one prefix (say ``ros2-foo.patch``)
+and a platform-specific patch under a *different* prefix (say
+``ros-jazzy-foo.osx.patch``), both prefixes already exist as their own
+dict entries by the time the cross-link step runs, so the two never
+merge. Whichever prefix vinca does *not* resolve as the package's
+final conda name for a given recipe simply never appears in that
+recipe's ``patches:`` list -- with no error and no warning. This
+exact bug orphaned ``ros-jazzy-sick-scan-xd.osx.patch`` for months
+before it was renamed to ``ros2-sick-scan-xd.osx.patch`` (matching the
+prefix jazzy actually resolves sick_scan_xd's own patch under).
+
+``check_patches_clean_apply.py`` does not catch this: it verifies that
+every patch file on disk applies cleanly to source, but never checks
+whether vinca's real name-resolution would actually attach that file
+to any package's generated recipe at all.
+
+What this script does
+----------------------
+Replicates vinca's exact patch-dict-construction and
+``add_package_name_variants`` shortname-stripping logic (kept in sync
+with whatever revision this repo's ``pixi.toml`` pins vinca to -- if
+that mechanism ever changes upstream, re-check this script). It groups
+patch-file prefixes by their computed "shortname" and flags any group
+where more than one *distinct* literal prefix was actually used by a
+file on disk: only one of those prefixes can ever be the resolved
+package name for a given recipe, so content under the others is dead.
+
+Exit code is non-zero (and the offending groups are printed) if any
+such collision is found.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent
+PATCH_DIR = REPO_ROOT / "patch"
+
+_ROS_DISTRO_RE = re.compile(r"^ros_distro:\s*(\S+)\s*$", re.MULTILINE)
+
+
+def get_ros_distro() -> str:
+    vinca_yaml = (REPO_ROOT / "vinca.yaml").read_text()
+    match = _ROS_DISTRO_RE.search(vinca_yaml)
+    if not match:
+        print("Could not find 'ros_distro:' in vinca.yaml", file=sys.stderr)
+        sys.exit(2)
+    return match.group(1)
+
+
+def build_patches_dict(patch_dir: Path) -> dict[str, dict[str, list[str]]]:
+    """Mirrors the glob loop in vinca/main.py that builds vinca_conf['_patches']."""
+    patches: dict[str, dict[str, list[str]]] = {}
+    for x in sorted(glob.glob(os.path.join(str(patch_dir), "*.patch"))):
+        splitted = os.path.basename(x).split(".")
+        if splitted[0] not in patches:
+            patches[splitted[0]] = {
+                "any": [],
+                "osx": [],
+                "linux": [],
+                "win": [],
+                "emscripten": [],
+            }
+        if len(splitted) == 3:
+            if splitted[1] in ("osx", "linux", "win", "emscripten"):
+                patches[splitted[0]][splitted[1]].append(x)
+                continue
+            if splitted[1] == "unix":
+                patches[splitted[0]]["linux"].append(x)
+                patches[splitted[0]]["osx"].append(x)
+                continue
+        patches[splitted[0]]["any"].append(x)
+    return patches
+
+
+def shortname_of(name: str, ros_distro: str) -> str:
+    """Mirrors the prefix-stripping in vinca/utils.py::add_package_name_variants."""
+    legacy_prefix = f"ros-{ros_distro}-"
+    if name.startswith(legacy_prefix):
+        return name[len(legacy_prefix):]
+    elif name.startswith("ros2-"):
+        return name[len("ros2-"):]
+    elif name.startswith("ros-"):
+        return name[len("ros-"):]
+    else:
+        return name
+
+
+def main() -> int:
+    ros_distro = get_ros_distro()
+    patches = build_patches_dict(PATCH_DIR)
+
+    groups: dict[str, list[str]] = {}
+    for prefix in patches:
+        groups.setdefault(shortname_of(prefix, ros_distro), []).append(prefix)
+
+    collisions = {
+        shortname: prefixes
+        for shortname, prefixes in groups.items()
+        if len(prefixes) > 1
+    }
+
+    if not collisions:
+        print(f"OK: no orphaned platform-specific patches ({len(patches)} patch-file prefixes scanned).")
+        return 0
+
+    print(
+        "ORPHANED PLATFORM PATCH RISK: the following packages have patch files "
+        "spread across more than one name-prefix variant. vinca's "
+        "add_package_name_variants() cross-links prefix variants via "
+        "dict.setdefault(), which is a no-op once a variant already exists as its "
+        "own entry -- so only ONE of the prefixes below will end up attached to "
+        "the package's real generated recipe; any platform-specific patch under "
+        "the others is silently never applied.\n",
+        file=sys.stderr,
+    )
+    for shortname, prefixes in sorted(collisions.items()):
+        print(f"  {shortname}:", file=sys.stderr)
+        for prefix in sorted(prefixes):
+            files = [
+                os.path.basename(f)
+                for platform_files in patches[prefix].values()
+                for f in platform_files
+            ]
+            print(f"    {prefix}: {', '.join(sorted(files))}", file=sys.stderr)
+    print(
+        "\nFix: rename the patch file(s) so every file for a given package shares "
+        "the SAME name prefix (matching whichever prefix that package's own "
+        "recipe.yaml actually resolves to -- check recipes/<pkg>/*/recipe.yaml's "
+        "source.patches entries, or regenerate recipes locally and inspect).",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pixi.toml

@@ -41,7 +41,8 @@ git = "*"
 [tasks]
 generate-recipes = { cmd = "vinca -m", depends-on = ["remove-recipes"] }
 generate-gha-workflows = { cmd = "vinca-gha --trigger-branch dummy_build_branch_as_it_is_unused -d ./recipes", depends-on = ["generate-recipes"] }
-check-patches = { cmd = "python check_patches_clean_apply.py", depends-on = ["generate-recipes"] }
+check-orphaned-patches = { cmd = "python check_orphaned_platform_patches.py", description = "Detect patch/ files vinca's add_package_name_variants() will never wire into any recipe because a same-package patch exists under a different name-prefix variant (see script docstring)." }
+check-patches = { cmd = "python check_patches_clean_apply.py", depends-on = ["generate-recipes", "check-orphaned-patches"] }
 check-deps = { cmd = "python check_dependency_compat.py", depends-on = ["generate-recipes"], description = "Solve one fake package containing every non-ROS dependency plus the mutex constraints to find pin conflicts before building anything. Run `python check_dependency_compat.py --stale` to list already-built artifacts that conflict with the current pins." }
 create_snapshot = { cmd = "vinca-snapshot -d humble -o rosdistro_snapshot.yaml" }
 upload = "rattler-build upload anaconda -o robostack-staging -a $ANACONDA_API_TOKEN"

vinca.yaml

@@ -31,6 +31,58 @@ rosdistro_additional_recipes: rosdistro_additional_recipes.yaml
 skip_existing:
   - https://conda.anaconda.org/robostack-staging/
 
+# --------------------------------------------------------------------------
+# Three related but DISTINCT ways to exclude a package -- read this before
+# adding to any of the three (vinca revision pinned in pixi.toml verified
+# against on 2026-09-06; re-check vinca/main.py + vinca/resolve.py if that
+# pin ever moves, in case the mechanism changes):
+#
+# 1. packages_select_by_deps, wrapped in `if: not <platform> then: [...]`
+#    (see below). This is the PRIMARY way to exclude a package's own
+#    recipe: vinca/main.py::get_selected_packages adds every name listed
+#    here to `selected_packages` unconditionally, before any skip-list is
+#    even consulted -- so simply never listing a package under the
+#    current platform's branch here is what keeps its own recipe from
+#    being generated.
+#
+# 2. packages_skip_by_deps (this list) only affects TRANSITIVE pull-in:
+#    it's passed as `ignore_pkgs` to `distro.get_depends()`, so it stops
+#    some OTHER selected package's dependency-closure walk from dragging
+#    the excluded package back in. It does NOT stop a package listed
+#    directly in packages_select_by_deps from being selected -- the two
+#    lists answer different questions ("should X be pulled in as someone
+#    else's dependency?" vs. "should X itself be built?").
+#
+# 3. packages_remove_from_deps (further below) is checked by
+#    vinca/resolve.py::should_skip_pkg via resolve_pkgname(), which is
+#    called BOTH when vinca resolves a package's OWN final name (in
+#    generate_fat_source -- an empty result makes it `continue`, i.e.
+#    skip generating that package's recipe entirely) AND when it resolves
+#    OTHER packages' host/run dependency names. So this list is really a
+#    THIRD, independent way to fully exclude a package's own build -- and
+#    it ALSO strips the package's name from every other recipe's
+#    dependency list as an inseparable side effect. If some other
+#    selected package legitimately needs to depend on the package you're
+#    excluding, packages_remove_from_deps is the WRONG tool (it removes
+#    both); use packages_select_by_deps's if-wrapper (+ packages_skip_by_deps
+#    if something's dependency closure would otherwise repull it) instead.
+#
+# Worked examples from real fixes in this repo:
+#   - robot_localization (win-64): needed ALL THREE together, because
+#     clearpath_control (itself unconditionally selected) transitively
+#     depended on it -- (1) alone left it selected via clearpath_control's
+#     closure. See commits 411b2f7d, 929734a9.
+#   - rclc_examples (win-64): excluded via (3) ALONE -- it has NO
+#     `if: not win` wrapper under packages_select_by_deps at all, and
+#     isn't in packages_skip_by_deps either; it's only ever excluded
+#     because it's listed under packages_remove_from_deps's win branch.
+#     A win-64 compile bug in this package looked "never fixed" until it
+#     was traced to the package being fully excluded by this mechanism.
+#   - ros-jazzy mavlink/mavros/mavros_extras/libmavconn: (1) alone was
+#     sufficient there -- confirmed via full recipe regeneration that no
+#     other selected package referenced them, so (2)/(3) were never
+#     needed for that case.
+# --------------------------------------------------------------------------
 packages_skip_by_deps:
 
   - if: not linux
@@ -102,6 +154,12 @@ packages_skip_by_deps:
   # to attempt blindly; skip for now.
   - as2_behaviors_trajectory_generation
 
+# See the "Three related but DISTINCT ways to exclude a package" block above
+# packages_skip_by_deps: this list (3) ALSO fully excludes a package's own
+# recipe (not just its appearance in others' deps) -- use packages_select_by_deps's
+# if-wrapper instead if you only want to stop this package's own build while
+# still letting another selected package depend on it.
+
 packages_remove_from_deps:
 
   - if: not linux
@@ -154,6 +212,12 @@ packages_remove_from_deps:
     then:
       - robot_localization
 
+# See the "Three related but DISTINCT ways to exclude a package" block above
+# packages_skip_by_deps: an `if: not <platform> then: [pkg]` branch here is
+# mechanism (1), the primary way to exclude pkg's own recipe for that
+# platform. Add to packages_skip_by_deps too if something else's dependency
+# closure would otherwise still pull it back in.
+
 packages_select_by_deps:
 
   # These are the packages that are build on all platforms, including wasm32