verify-action-build: per-ecosystem exemption list for lock-file check

Some upstream projects are libraries or CLI tools that also ship a GitHub
Action wrapper — e.g. pypa/cibuildwheel (Python library on PyPI),
dart-lang/setup-dart (Dart package on pub.dev). These repos legitimately
don't commit a lock file because doing so would over-constrain their
library consumers. Hard-failing on those would block otherwise-valid
Dependabot bumps.

Add lock_file_exemptions.yml at the repo root listing per-(org/repo)
per-ecosystem exemptions. analyze_lock_files consults this file and
reports an exempted manifest as a dim skipped entry (⊘) instead of a
red failure. Exemptions are scoped per-ecosystem, so an action exempted
for one ecosystem is still checked for others it declares (e.g.
dart-lang/setup-dart's node side must still have package-lock.json).

Preseeded entries:
  pypa/cibuildwheel → python   (library on PyPI)
  dart-lang/setup-dart → dart  (Dart library convention)

Lookups lowercase org/repo so case mismatches don't silently miss.

Author: potiuk

lock_file_exemptions.yml

@@ -0,0 +1,36 @@
+# lock_file_exemptions.yml
+#
+# Per-(org/repo) per-ecosystem exemptions from the "every dependency manifest
+# must have a matching lock file" check enforced by verify-action-build.
+#
+# When is an exemption appropriate?  Only when the upstream repo is primarily
+# a library or CLI tool that also ships a GitHub Action wrapper, and that
+# project's ecosystem convention is to *not* commit a lock file.  Typical
+# examples:
+#   * Python libraries published to PyPI — lock files would pin transitive
+#     versions that downstream library consumers shouldn't be forced into.
+#   * Dart packages published to pub.dev — pubspec.lock is deliberately
+#     .gitignore'd for libraries.
+#
+# Exemptions are scoped per-ecosystem, so a project exempted for Python is
+# still checked for its Node side (if it has one).
+#
+# Ecosystem keys (must match one of the names in analyze_lock_files):
+#   node  python  deno  dart  ruby  go  rust
+#
+# Format:
+#   org/repo:
+#     - ecosystem1
+#     - ecosystem2
+
+pypa/cibuildwheel:
+  # cibuildwheel is a Python library published to PyPI.  Its pyproject.toml
+  # declares runtime deps for users who `pip install cibuildwheel`; committing
+  # a lock file would over-constrain library consumers.
+  - python
+
+dart-lang/setup-dart:
+  # The repo is a Dart package (pubspec.yaml) shipped as an action.  Dart
+  # convention for library packages is to not commit pubspec.lock.  The node
+  # side of this action is still checked (package.json → package-lock.json).
+  - dart

utils/tests/verify_action_build/test_security.py

@@ -658,3 +658,98 @@ def test_multiple_ecosystems_all_missing_aggregates_errors(self):
         }
         errors = self._run(files)
         assert len(errors) == 3
+
+    # --- Exemptions -------------------------------------------------------
+
+    def _run_with_exemptions(
+        self,
+        files: dict,
+        exemptions: dict,
+        org: str = "org",
+        repo: str = "repo",
+    ) -> list[str]:
+        def fetch(o, r, commit, path):
+            return files.get(path)
+
+        with mock.patch(
+            "verify_action_build.security.fetch_file_from_github",
+            side_effect=fetch,
+        ):
+            return analyze_lock_files(org, repo, "a" * 40, exemptions=exemptions)
+
+    def test_exemption_skips_matching_ecosystem(self):
+        # pyproject.toml with deps but no lock — normally fails; exempted here.
+        files = {
+            "pyproject.toml": '[project]\ndependencies = ["requests"]\n',
+        }
+        errors = self._run_with_exemptions(
+            files, {("org", "repo"): {"python"}},
+        )
+        assert errors == []
+
+    def test_exemption_does_not_skip_other_ecosystems(self):
+        # Exempt only python; node still fails.
+        files = {
+            "pyproject.toml": '[project]\ndependencies = ["requests"]\n',
+            "package.json": "{}",
+        }
+        errors = self._run_with_exemptions(
+            files, {("org", "repo"): {"python"}},
+        )
+        assert len(errors) == 1
+        assert "package.json" in errors[0]
+
+    def test_exemption_case_insensitive(self):
+        # Look-up key lowercases org/repo, so an exemption entry written as
+        # "Pypa/cibuildwheel" matches a run on "pypa/cibuildwheel".
+        files = {"pyproject.toml": '[project]\ndependencies = ["a"]\n'}
+        errors = self._run_with_exemptions(
+            files, {("pypa", "cibuildwheel"): {"python"}},
+            org="Pypa", repo="CIBuildWheel",
+        )
+        assert errors == []
+
+    def test_exemption_for_different_repo_does_not_apply(self):
+        files = {"pyproject.toml": '[project]\ndependencies = ["a"]\n'}
+        errors = self._run_with_exemptions(
+            files, {("other", "project"): {"python"}},
+        )
+        assert len(errors) == 1
+
+    # --- Exemption file parser -------------------------------------------
+
+    def test_exemption_file_parses(self, tmp_path):
+        from verify_action_build.security import _load_lock_file_exemptions
+
+        yml = tmp_path / "lock_file_exemptions.yml"
+        yml.write_text(
+            "# comment\n"
+            "pypa/cibuildwheel:\n"
+            "  - python\n"
+            "\n"
+            "dart-lang/setup-dart:\n"
+            "  - dart  # trailing comment\n"
+        )
+        result = _load_lock_file_exemptions(yml)
+        assert result == {
+            ("pypa", "cibuildwheel"): {"python"},
+            ("dart-lang", "setup-dart"): {"dart"},
+        }
+
+    def test_exemption_file_missing_returns_empty(self, tmp_path):
+        from verify_action_build.security import _load_lock_file_exemptions
+
+        result = _load_lock_file_exemptions(tmp_path / "does-not-exist.yml")
+        assert result == {}
+
+    def test_exemption_file_multiple_ecosystems_per_repo(self, tmp_path):
+        from verify_action_build.security import _load_lock_file_exemptions
+
+        yml = tmp_path / "lock_file_exemptions.yml"
+        yml.write_text(
+            "some/multiecosystem-repo:\n"
+            "  - python\n"
+            "  - dart\n"
+        )
+        result = _load_lock_file_exemptions(yml)
+        assert result[("some", "multiecosystem-repo")] == {"python", "dart"}

utils/verify_action_build/security.py

@@ -22,6 +22,7 @@
 import os
 import re
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Iterator
 
 import requests
@@ -40,6 +41,53 @@
 # Orgs we trust to the point of not descending into their nested action graph.
 TRUSTED_ORGS = {"actions", "github"}
 
+# Exemptions file for the lock-file-presence check.  Path matches the
+# convention used by approved_actions.ACTIONS_YML.
+LOCK_FILE_EXEMPTIONS_YML = (
+    Path(__file__).resolve().parent.parent.parent / "lock_file_exemptions.yml"
+)
+
+
+def _load_lock_file_exemptions(
+    path: Path = LOCK_FILE_EXEMPTIONS_YML,
+) -> dict[tuple[str, str], set[str]]:
+    """Parse lock_file_exemptions.yml into {(org, repo): {ecosystems}}.
+
+    Uses a minimal line-based parser rather than PyYAML to keep the dependency
+    surface small (the rest of this project also avoids pulling in yaml).
+    Supported subset:
+        org/repo:
+          - ecosystem1
+          - ecosystem2
+    Comments (``#``) and blank lines are ignored.  Keys are lowercased so
+    lookups are case-insensitive (``Pypa/cibuildwheel`` == ``pypa/cibuildwheel``).
+    """
+    result: dict[tuple[str, str], set[str]] = {}
+    if not path.exists():
+        return result
+
+    current: tuple[str, str] | None = None
+    for raw in path.read_text().splitlines():
+        line = raw.split("#", 1)[0].rstrip()
+        if not line.strip():
+            continue
+        if not line[0].isspace() and line.endswith(":"):
+            orgrepo = line[:-1].strip().strip("'\"")
+            if "/" in orgrepo:
+                org, repo = orgrepo.split("/", 1)
+                current = (org.lower(), repo.lower())
+                result.setdefault(current, set())
+            else:
+                current = None
+            continue
+        if current is not None:
+            stripped = line.lstrip()
+            if stripped.startswith("- "):
+                ecosystem = stripped[2:].strip().strip("'\"")
+                if ecosystem:
+                    result[current].add(ecosystem)
+    return result
+
 
 @dataclass
 class VisitedAction:
@@ -559,6 +607,7 @@ def analyze_scripts(
 
 def analyze_lock_files(
     org: str, repo: str, commit_hash: str, sub_path: str = "",
+    exemptions: dict[tuple[str, str], set[str]] | None = None,
 ) -> list[str]:
     """Verify each detected dependency manifest has a matching lock file.
 
@@ -574,8 +623,17 @@ def analyze_lock_files(
     (e.g. a bare pyproject.toml with only tool config, a Rust library crate
     that conventionally doesn't commit Cargo.lock) are reported as skipped.
 
+    ``exemptions`` maps ``(org, repo)`` to a set of ecosystem names where a
+    missing lock file is tolerated — for library-first projects (cibuildwheel,
+    setup-dart) that don't commit lock files per their ecosystem convention.
+    Defaults to the contents of ``lock_file_exemptions.yml`` at the repo root.
+
     Returns a list of error strings (empty = pass).
     """
+    if exemptions is None:
+        exemptions = _load_lock_file_exemptions()
+    exempted_ecosystems = exemptions.get((org.lower(), repo.lower()), set())
+
     errors: list[str] = []
     header_shown = False
 
@@ -684,6 +742,11 @@ def _find(name: str) -> tuple[str, str] | None:
             console.print(
                 f"  [green]✓[/green] {ecosystem}: {manifest_link} → {lock_link}"
             )
+        elif ecosystem in exempted_ecosystems:
+            console.print(
+                f"  [dim]⊘[/dim] {ecosystem}: {manifest_link} has no matching lock file "
+                f"— exempted in lock_file_exemptions.yml (library-first project)"
+            )
         else:
             console.print(
                 f"  [red]✗[/red] {ecosystem}: {manifest_link} has no matching lock file "

utils/verify_action_build/verification.py

@@ -287,7 +287,7 @@ def verify_single_action(
         else:
             checks_performed.append((
                 "Lock file presence", "pass",
-                "all detected manifests have lock files",
+                "all detected manifests have lock files (or are exempted)",
             ))
 
         if not is_js_action: