repoutils 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
repoutils/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """Repository tooling for Python projects that use uv, just and GitHub Actions."""
repoutils/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ """``python -m repoutils``, the same as the ``repoutils`` command."""
2
+
3
+ from repoutils.cli import main
4
+
5
+ raise SystemExit(main())
repoutils/cli.py ADDED
@@ -0,0 +1,96 @@
1
+ """The ``repoutils`` command: ``repoutils <command> [args...]``.
2
+
3
+ Each command is a module in ``repoutils.commands`` with a ``run(argv) -> int``
4
+ function, which parses its own arguments. Modules are imported only when their
5
+ command runs, so ``repoutils --help`` stays fast.
6
+ """
7
+
8
+ import importlib
9
+ import sys
10
+ from collections.abc import Callable
11
+ from dataclasses import dataclass
12
+ from importlib.metadata import PackageNotFoundError, version
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class Command:
17
+ name: str
18
+ module: str
19
+ summary: str
20
+
21
+
22
+ GROUPS: dict[str, list[Command]] = {
23
+ "Repo hygiene": [
24
+ Command("check-whitespace", "check_whitespace", "Check Git-tracked text files for trailing whitespace"),
25
+ Command(
26
+ "check-sentence-per-line", "check_sentence_per_line", "Check Markdown files keep one sentence per line"
27
+ ),
28
+ Command(
29
+ "check-blame-ignore-revs", "check_blame_ignore_revs", "Check .git-blame-ignore-revs lists real commits"
30
+ ),
31
+ Command("check-screenshots-dir", "check_screenshots_dir", "Check only .gitignore is tracked in screenshots/"),
32
+ Command("git-config-setup", "git_config_setup", "Set the repo's local Git config (blame.ignoreRevsFile)"),
33
+ Command("long-files", "long_files", "List files over the line limit, or post that to a PR"),
34
+ ],
35
+ "GitHub Actions workflows": [
36
+ Command("check-pins", "check_pins", "Check workflows pin the project's uv and just versions"),
37
+ Command("check-checkout-credentials", "check_checkout_credentials", "Check checkouts set persist-credentials"),
38
+ Command("claude-route", "claude_route", "Decide which Claude workflow a comment (on stdin) is for"),
39
+ ],
40
+ "uv and Dependabot": [
41
+ Command(
42
+ "requirements-min-versions", "requirements_min_versions", "Check or fix dependency minimums vs uv.lock"
43
+ ),
44
+ Command("dependabot-relock", "dependabot_relock", "Re-lock a Dependabot branch's uv.lock with this uv"),
45
+ Command("check-lock-platforms", "check_lock_platforms", "Check uv.lock only has wheels for allowed platforms"),
46
+ ],
47
+ "PR reporting": [
48
+ Command("post-comment", "post_comment", "Post a Markdown file to a PR, editing or hiding the last one"),
49
+ Command("post-patch-coverage", "post_patch_coverage", "Post a diff-cover patch coverage report to a PR"),
50
+ Command("wait-for-base-coverage", "wait_for_base_coverage", "Wait for Codecov to have a PR base's coverage"),
51
+ Command("post-screenshots", "post_screenshots", "Post screenshots to a PR as a comment"),
52
+ Command("recreate-pr", "recreate_pr", "Recreate a PR as a draft and close the original"),
53
+ ],
54
+ "Releases": [
55
+ Command("check-attestations", "check_attestations", "Check every distribution has a PEP 740 attestation"),
56
+ ],
57
+ }
58
+
59
+ COMMANDS = {command.name: command for commands in GROUPS.values() for command in commands}
60
+
61
+
62
+ def _version() -> str:
63
+ try:
64
+ return version("repoutils")
65
+ except PackageNotFoundError: # pragma: no cover - only when run from an uninstalled checkout
66
+ return "unknown"
67
+
68
+
69
+ def usage() -> str:
70
+ width = max(len(name) for name in COMMANDS)
71
+ lines = ["usage: repoutils <command> [args...]", "", "Commands:"]
72
+ for group, commands in GROUPS.items():
73
+ lines += ["", f" {group}:"]
74
+ lines += [f" {command.name:<{width}} {command.summary}" for command in commands]
75
+ lines += ["", "Run `repoutils <command> --help` for a command's options."]
76
+ return "\n".join(lines)
77
+
78
+
79
+ def load(name: str) -> Callable[[list[str]], int]:
80
+ """The ``run`` function of the named command."""
81
+ run: Callable[[list[str]], int] = importlib.import_module(f"repoutils.commands.{COMMANDS[name].module}").run
82
+ return run
83
+
84
+
85
+ def main(argv: list[str] | None = None) -> int:
86
+ args = sys.argv[1:] if argv is None else argv
87
+ if not args or args[0] in ("-h", "--help", "help"):
88
+ print(usage())
89
+ return 0 if args else 2
90
+ if args[0] == "--version":
91
+ print(f"repoutils {_version()}")
92
+ return 0
93
+ if args[0] not in COMMANDS:
94
+ print(f"repoutils: unknown command {args[0]!r}\n\n{usage()}", file=sys.stderr)
95
+ return 2
96
+ return load(args[0])(args[1:])
@@ -0,0 +1 @@
1
+ """One module per ``repoutils`` command, each with a ``run(argv) -> int``."""
@@ -0,0 +1,59 @@
1
+ """Check that every distribution in a directory (default dist/) has a non-empty
2
+ PEP 740 publish attestation beside it, as astral-sh/attest-action writes them:
3
+ `<file>.publish.attestation`.
4
+
5
+ uv publish uploads a file's attestation if it finds one and quietly uploads the
6
+ file without one if not, so the publish jobs run this between attest-action and
7
+ uv publish, to stop rather than publish a release with no provenance. The
8
+ Attestations workflow runs it on PRs that could break that, without uploading.
9
+
10
+ Prints a GitHub Actions ::error:: line for each problem, which also reads fine
11
+ outside Actions."""
12
+
13
+ import argparse
14
+ import sys
15
+ from pathlib import Path
16
+
17
+ SUFFIX = ".publish.attestation"
18
+
19
+
20
+ def distributions(dist: Path) -> list[Path]:
21
+ """The wheels and sdists in dist, sorted."""
22
+ return sorted([*dist.glob("*.whl"), *dist.glob("*.tar.gz")])
23
+
24
+
25
+ def problems(dist: Path) -> tuple[list[str], int]:
26
+ """Each distribution in dist with no attestation or an empty one, and how
27
+ many distributions there are. No distribution at all is a problem too."""
28
+ files = distributions(dist)
29
+ if not files:
30
+ return [f"No distributions found in {dist.as_posix()}/"], 0
31
+ found: list[str] = []
32
+ for file in files:
33
+ attestation = file.with_name(file.name + SUFFIX)
34
+ if not attestation.is_file():
35
+ found.append(f"No attestation for {file.as_posix()}")
36
+ elif not attestation.stat().st_size:
37
+ found.append(f"Empty attestation for {file.as_posix()}")
38
+ return found, len(files)
39
+
40
+
41
+ def main(argv: list[str] | None = None) -> int:
42
+ args = sys.argv[1:] if argv is None else argv
43
+ if len(args) > 1:
44
+ print("usage: check_attestations.py [DIST_DIR]", file=sys.stderr)
45
+ return 2
46
+ dist = Path(args[0] if args else "dist")
47
+ found, count = problems(dist)
48
+ for problem in found:
49
+ print(f"::error::{problem}")
50
+ if found:
51
+ return 1
52
+ print(f"all {count} distributions in {dist.as_posix()}/ have an attestation")
53
+ return 0
54
+
55
+
56
+ def run(argv: list[str]) -> int:
57
+ parser = argparse.ArgumentParser(prog="repoutils check-attestations", description=__doc__.splitlines()[0])
58
+ parser.add_argument("dist", nargs="?", default="dist", help="directory of distributions (default: dist)")
59
+ return main([parser.parse_args(argv).dist])
@@ -0,0 +1,69 @@
1
+ """Check that .git-blame-ignore-revs lists only real commits from the target branch's history.
2
+
3
+ Git silently ignores an entry naming no commit, so a typo or a pre-squash hash
4
+ would leave the reformatting commit it was meant to hide in `git blame`. This
5
+ fails unless every non-comment line is a full lowercase hash of a commit that's
6
+ an ancestor of the target (so CI needs the full history).
7
+
8
+ The target is HEAD unless given as the only argument. On a PR, CI passes the
9
+ base branch's commit: as PRs are squash-merged, a commit from the PR itself
10
+ is an ancestor of the PR's head but won't be on the base branch once merged.
11
+ """
12
+
13
+ import argparse
14
+ import re
15
+ import subprocess
16
+ from pathlib import Path
17
+
18
+ IGNORE_REVS = Path(".git-blame-ignore-revs")
19
+ HASH_RE = re.compile(r"[0-9a-f]{40}")
20
+
21
+
22
+ def _git(*args: str) -> subprocess.CompletedProcess[str]:
23
+ return subprocess.run(["git", *args], check=False, capture_output=True, text=True)
24
+
25
+
26
+ def _problems(target: str) -> list[str]:
27
+ if not IGNORE_REVS.is_file():
28
+ return [f"{IGNORE_REVS} is missing"]
29
+ problems = []
30
+ for line_number, line in enumerate(IGNORE_REVS.read_text(encoding="utf-8").splitlines(), 1):
31
+ rev = line.strip()
32
+ if not rev or rev.startswith("#"):
33
+ continue
34
+ if HASH_RE.fullmatch(rev) is None:
35
+ problems.append(f"{IGNORE_REVS}:{line_number}: not a full 40-character lowercase hex hash: {rev!r}")
36
+ continue
37
+ object_type = _git("cat-file", "-t", rev)
38
+ if object_type.returncode != 0:
39
+ problems.append(f"{IGNORE_REVS}:{line_number}: {rev} doesn't name an existing Git object")
40
+ continue
41
+ if object_type.stdout.strip() != "commit":
42
+ problems.append(f"{IGNORE_REVS}:{line_number}: {rev} is a {object_type.stdout.strip()}, not a commit")
43
+ continue
44
+ ancestor = _git("merge-base", "--is-ancestor", rev, target)
45
+ if ancestor.returncode == 1:
46
+ problems.append(f"{IGNORE_REVS}:{line_number}: {rev} is not an ancestor of {target}")
47
+ elif ancestor.returncode != 0:
48
+ problems.append(
49
+ f"{IGNORE_REVS}:{line_number}: couldn't check whether {rev} is an ancestor of {target} "
50
+ f"(exit {ancestor.returncode})"
51
+ )
52
+ return problems
53
+
54
+
55
+ def main(target: str = "HEAD") -> int:
56
+ problems = _problems(target)
57
+ if problems:
58
+ print("Problems in .git-blame-ignore-revs:")
59
+ for problem in problems:
60
+ print(f"- {problem}")
61
+ return 1
62
+ print(f".git-blame-ignore-revs only lists real commit hashes that are ancestors of {target}.")
63
+ return 0
64
+
65
+
66
+ def run(argv: list[str]) -> int:
67
+ parser = argparse.ArgumentParser(prog="repoutils check-blame-ignore-revs", description=__doc__.splitlines()[0])
68
+ parser.add_argument("target", nargs="?", default="HEAD", help="the commit every entry must be an ancestor of")
69
+ return main(parser.parse_args(argv).target)
@@ -0,0 +1,52 @@
1
+ """Check that every actions/checkout step in the workflows and local composite
2
+ actions says whether it keeps its token: `persist-credentials: false`, or
3
+ `persist-credentials: true` in a job that pushes with it.
4
+
5
+ Left unset, checkout keeps the token where every later step of the job can read
6
+ it. jactionlint's artipacked rule would catch that, but it doesn't report
7
+ actions/checkout v6 and later, which moved the token out of .git/config into a
8
+ file the git config includes (so an upload of the workspace no longer publishes
9
+ it, but any step can still read it)."""
10
+
11
+ import argparse
12
+ import sys
13
+ from pathlib import Path
14
+
15
+ from repoutils.commands.check_pins import pins, workflow_files
16
+
17
+ CHECKOUT = "actions/checkout"
18
+ KEY = "persist-credentials"
19
+
20
+
21
+ def problems(root: Path) -> tuple[list[str], int]:
22
+ """Each checkout step that doesn't set persist-credentials to true or false,
23
+ and how many checkout steps there are. No checkout step at all is a problem
24
+ too, as it more likely means they're no longer recognized."""
25
+ found: list[str] = []
26
+ count = 0
27
+ for path in workflow_files(root):
28
+ for value in pins(path.read_text(), CHECKOUT, KEY):
29
+ count += 1
30
+ if value not in ("true", "false"):
31
+ setting = f"{KEY}: {value}" if value else f"no {KEY}"
32
+ found.append(f"{path.relative_to(root).as_posix()}: a {CHECKOUT} step has {setting}, not false or true")
33
+ if not count:
34
+ found.append(f"no workflow or action has a {CHECKOUT} step")
35
+ return found, count
36
+
37
+
38
+ def main(root: Path = Path()) -> int:
39
+ found, count = problems(root)
40
+ for problem in found:
41
+ print(problem, file=sys.stderr)
42
+ if found:
43
+ return 1
44
+ print(f"all {count} {CHECKOUT} steps set {KEY}")
45
+ return 0
46
+
47
+
48
+ def run(argv: list[str]) -> int:
49
+ argparse.ArgumentParser(
50
+ prog="repoutils check-checkout-credentials", description=__doc__.splitlines()[0]
51
+ ).parse_args(argv)
52
+ return main()
@@ -0,0 +1,146 @@
1
+ """Check that uv.lock only has wheels for the platforms the project allows.
2
+
3
+ ``[tool.repoutils.lock-platforms]`` lists them: ``supported`` (the platforms
4
+ ``[tool.uv] environments`` is meant to allow) and ``tolerated`` (ones uv keeps
5
+ wheels for despite ``environments``, such as iOS and Emscripten). Each entry is
6
+ ``os`` or ``os:arch``, with ``*`` for any arch, matched against a wheel's
7
+ platform tag split into its OS and arch (``manylinux_2_17_x86_64`` is
8
+ ``manylinux:x86_64``; a name containing ``linux`` also matches ``linux``).
9
+ """
10
+
11
+ import argparse
12
+ import dataclasses
13
+ import re
14
+ import tomllib
15
+ from enum import StrEnum
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ from repoutils import config
20
+
21
+
22
+ # How _classify_platform treats an (OS, arch) pair, as split by _split_platform.
23
+ # SUPPORTED platforms are ones we intend to support, matching `[tool.uv]
24
+ # environments` in pyproject.toml; TOLERATED ones are platforms uv keeps wheels
25
+ # for even though `environments` excludes them. uv.lock may only have wheels for
26
+ # these two.
27
+ class PlatformClassification(StrEnum):
28
+ SUPPORTED = "supported"
29
+ TOLERATED = "tolerated"
30
+ UNSUPPORTED = "unsupported"
31
+
32
+
33
+ DEFAULT_SUPPORTED = ("any", "linux:x86_64", "linux:aarch64", "macosx")
34
+ DEFAULT_TOLERATED = ("ios", "pyemscripten")
35
+
36
+
37
+ @dataclasses.dataclass(frozen=True)
38
+ class Platforms:
39
+ """The ``os`` or ``os:arch`` patterns a project supports or tolerates."""
40
+
41
+ supported: tuple[str, ...] = DEFAULT_SUPPORTED
42
+ tolerated: tuple[str, ...] = DEFAULT_TOLERATED
43
+
44
+ @classmethod
45
+ def from_config(cls, root: Path = Path()) -> "Platforms":
46
+ table = config.section("lock-platforms", root)
47
+ where = "[tool.repoutils.lock-platforms]"
48
+ return cls(
49
+ tuple(config.string_list(table, "supported", list(DEFAULT_SUPPORTED), where)),
50
+ tuple(config.string_list(table, "tolerated", list(DEFAULT_TOLERATED), where)),
51
+ )
52
+
53
+
54
+ def _matches(pattern: str, os: str, arch: str | None) -> bool:
55
+ """Whether ``os``/``arch`` matches ``pattern``: ``os`` alone allows any
56
+ arch, ``os:arch`` only that one (``*`` for any). ``linux`` matches any OS
57
+ name containing it (``manylinux``, ``musllinux``)."""
58
+ want_os, _, want_arch = pattern.partition(":")
59
+ if want_os != os and not (want_os == "linux" and "linux" in os):
60
+ return False
61
+ return want_arch in ("", "*") or want_arch == arch
62
+
63
+
64
+ def _classify_platform(os_arch: tuple[str, str | None], platforms: Platforms = Platforms()) -> PlatformClassification:
65
+ os, arch = os_arch
66
+ if any(_matches(pattern, os, arch) for pattern in platforms.supported):
67
+ return PlatformClassification.SUPPORTED
68
+ if any(_matches(pattern, os, arch) for pattern in platforms.tolerated):
69
+ return PlatformClassification.TOLERATED
70
+ return PlatformClassification.UNSUPPORTED
71
+
72
+
73
+ # An OS name, any version glued onto it (`manylinux2014`) or following it in
74
+ # `_<number>` parts (`macosx_10_15`), then the arch, which may itself contain
75
+ # `_` (`x86_64`) but never starts with a digit.
76
+ _PLATFORM_RE = re.compile(r"(?P<os>[a-z]+?)\d*(?:_\d+)*_(?P<arch>[a-z].*)")
77
+
78
+
79
+ def _split_platform(platform: str) -> tuple[str, str | None]:
80
+ if platform == "any":
81
+ return "any", None
82
+ if platform == "win32": # the one tag with no "_<arch>" suffix
83
+ return "win", "x86"
84
+ m = _PLATFORM_RE.fullmatch(platform)
85
+ if m is None:
86
+ raise ValueError(f"unrecognised wheel platform tag: {platform}")
87
+ return m["os"], m["arch"]
88
+
89
+
90
+ def _wheel_platforms(filename: str) -> list[str]:
91
+ # A wheel's platform tag is its last `-`-separated field, and may hold
92
+ # several tags joined by `.` (e.g. `manylinux_2_17_x86_64.manylinux2014_x86_64`).
93
+ return filename.removesuffix(".whl").split("-")[-1].split(".")
94
+
95
+
96
+ def _classify_tag(platform: str, platforms: Platforms = Platforms()) -> PlatformClassification:
97
+ """How _classify_platform treats a wheel's platform tag; one it can't split is UNSUPPORTED."""
98
+ try:
99
+ return _classify_platform(_split_platform(platform), platforms)
100
+ except ValueError:
101
+ return PlatformClassification.UNSUPPORTED
102
+
103
+
104
+ def _wheel_filename(package_name: str, wheel: dict[str, Any]) -> str:
105
+ # Registry wheels have a `url`; local ones a `path` or `filename`.
106
+ location: str | None = wheel.get("url") or wheel.get("path") or wheel.get("filename")
107
+ if location is None:
108
+ raise ValueError(f"wheel in {package_name} has no url, path or filename")
109
+ return location.split("?", 1)[0].split("#", 1)[0].rsplit("/", 1)[-1]
110
+
111
+
112
+ def _disallowed_wheels(lock: dict[str, Any], platforms: Platforms = Platforms()) -> list[tuple[str, str, str]]:
113
+ """``(package, wheel filename, platform tag)`` for each of *lock*'s wheels for an UNSUPPORTED platform."""
114
+ disallowed = []
115
+ packages: list[dict[str, Any]] = lock.get("package", [])
116
+ for package in packages:
117
+ wheels: list[dict[str, Any]] = package.get("wheels", [])
118
+ for wheel in wheels:
119
+ filename = _wheel_filename(package["name"], wheel)
120
+ for platform in _wheel_platforms(filename):
121
+ if _classify_tag(platform, platforms) == PlatformClassification.UNSUPPORTED:
122
+ disallowed.append((package["name"], filename, platform))
123
+ return disallowed
124
+
125
+
126
+ def main() -> int:
127
+ lock = tomllib.loads(Path("uv.lock").read_text(encoding="utf-8"))
128
+ disallowed = _disallowed_wheels(lock, Platforms.from_config())
129
+ if disallowed:
130
+ print("uv.lock has wheels for platforms that aren't allowed:")
131
+ for name, filename, platform in disallowed:
132
+ print(f"- {name}: {filename} ({platform})")
133
+ print(
134
+ "Check `[tool.uv] environments` in pyproject.toml. If the platform "
135
+ "should be supported, add it there and to `supported` in "
136
+ "[tool.repoutils.lock-platforms]; if uv keeps its wheels despite "
137
+ "`environments`, add it to `tolerated` there."
138
+ )
139
+ return 1
140
+ print("uv.lock only has wheels for allowed platforms.")
141
+ return 0
142
+
143
+
144
+ def run(argv: list[str]) -> int:
145
+ argparse.ArgumentParser(prog="repoutils check-lock-platforms", description=__doc__.splitlines()[0]).parse_args(argv)
146
+ return main()
@@ -0,0 +1,177 @@
1
+ """Check that every workflow or local composite action step that installs uv
2
+ or just pins the version the project requires: pyproject.toml's [tool.uv]
3
+ required-version minimum and the justfile's minimum-version. A Dockerfile's
4
+ ghcr.io/astral-sh/uv stage, if there is one, must use that uv too."""
5
+
6
+ import argparse
7
+ import itertools
8
+ import re
9
+ import sys
10
+ import tomllib
11
+ from pathlib import Path
12
+
13
+ # (action, the `with:` input that pins its version)
14
+ UV = ("astral-sh/setup-uv", "version")
15
+ JUST = ("extractions/setup-just", "just-version")
16
+
17
+ _STEP_RE = re.compile(r"^(?P<indent>\s*)- ")
18
+ # A step's own `- ` marker, which YAML lets have more than one space.
19
+ _ITEM_RE = re.compile(r"^\s*-\s+")
20
+ _USES_RE = re.compile(r"^uses:\s*[\"']?(?P<action>[^@\s\"']+)@")
21
+ _WITH_RE = re.compile(r"^with:\s*(?:#.*)?$")
22
+ _JUST_MIN_RE = re.compile(r"^set minimum-version := '(?P<version>[^']+)'$", re.MULTILINE)
23
+ # The tag, without any @sha256: digest.
24
+ # A FROM line's flags (e.g. --platform=$BUILDPLATFORM) come before the image.
25
+ _DOCKER_UV_RE = re.compile(
26
+ r"^FROM\s+(?:--\S+\s+)*ghcr\.io/astral-sh/uv:(?P<version>[^\s@]+)", re.MULTILINE | re.IGNORECASE
27
+ )
28
+
29
+
30
+ def steps(text: str) -> list[list[str]]:
31
+ """The outermost YAML sequence items in a workflow (so each job step, but
32
+ not a list nested in one), each as its lines: an item runs from its `- `
33
+ line up to the next line (ignoring blanks and comments) indented no deeper
34
+ than that `- `."""
35
+ result: list[list[str]] = []
36
+ current: list[str] | None = None
37
+ indent = -1
38
+ for line in text.splitlines():
39
+ stripped = line.strip()
40
+ if current is not None and (
41
+ not stripped or stripped.startswith("#") or len(line) - len(line.lstrip()) > indent
42
+ ):
43
+ current.append(line)
44
+ elif match := _STEP_RE.match(line):
45
+ current = [line]
46
+ indent = len(match["indent"])
47
+ result.append(current)
48
+ else:
49
+ current = None
50
+ return result
51
+
52
+
53
+ def inputs(step: list[str]) -> list[str]:
54
+ """The lines of a step's `with:` mapping that start one of its keys, so
55
+ that a key in another of the step's mappings (`env:`), or a line of a
56
+ multi-line value (`sparse-checkout: |`), isn't taken for an input."""
57
+ lines = [line for line in step if line.strip() and not line.strip().startswith("#")]
58
+ for i, (indent, key) in enumerate(_keys(lines)):
59
+ if _WITH_RE.match(key):
60
+ mapping = list(itertools.takewhile(lambda body: _depth(body) > indent, lines[i + 1 :]))
61
+ return [key for key in mapping if _depth(key) == _depth(mapping[0])]
62
+ return []
63
+
64
+
65
+ def _keys(lines: list[str]) -> list[tuple[int, str]]:
66
+ """Each line of a step (blanks and comments already dropped) with its
67
+ indent and, where it starts one of the step's own keys, that key's text, or
68
+ "" where it doesn't. The step's keys sit just past its `- `, so a line
69
+ deeper in (in a `run: |` script, say) isn't taken for one of them. A
70
+ step always has its `- ` line, so lines is never empty."""
71
+ item = _ITEM_RE.match(lines[0])
72
+ key_depth = item.end() if item else _depth(lines[0])
73
+ keys = [(key_depth, lines[0][key_depth:])]
74
+ keys += [(_depth(line), line.strip() if _depth(line) == key_depth else "") for line in lines[1:]]
75
+ return keys
76
+
77
+
78
+ def _uses(step: list[str]) -> str | None:
79
+ """The action a step uses, or None if it runs a script instead."""
80
+ lines = [line for line in step if line.strip() and not line.strip().startswith("#")]
81
+ for _, key in _keys(lines):
82
+ if match := _USES_RE.match(key):
83
+ return match["action"]
84
+ return None
85
+
86
+
87
+ def _depth(line: str) -> int:
88
+ return len(line) - len(line.lstrip())
89
+
90
+
91
+ def pins(text: str, action: str, key: str) -> list[str | None]:
92
+ """The value of input key in each step of a workflow that uses action, or
93
+ None where that step doesn't set it."""
94
+ # The whole value, less its quotes or a trailing comment, so an unexpected
95
+ # one (`${{ env.UV }}`, `latest`, `"0.13.6 # x"`) is reported as written.
96
+ key_re = re.compile(
97
+ rf"""^\s*{re.escape(key)}:\s*(?:"(?P<double>[^"]*)"|'(?P<single>[^']*)'|(?P<plain>.*?))\s*(?:\s#.*)?$"""
98
+ )
99
+ found: list[str | None] = []
100
+ for step in steps(text):
101
+ if _uses(step) == action:
102
+ values = [
103
+ next(v for v in m.groups() if v is not None) for line in inputs(step) if (m := key_re.match(line))
104
+ ]
105
+ found.append(values[0] if values else None)
106
+ return found
107
+
108
+
109
+ def workflow_files(root: Path) -> list[Path]:
110
+ """The workflows, and the local composite actions they use, whose steps the
111
+ checks read: .github/workflows/*.y*ml and .github/actions/**/action.y*ml."""
112
+ github = root / ".github"
113
+ return sorted([*(github / "workflows").glob("*.y*ml"), *(github / "actions").glob("**/action.y*ml")])
114
+
115
+
116
+ def minimums(root: Path) -> dict[tuple[str, str], str]:
117
+ with (root / "pyproject.toml").open("rb") as f:
118
+ required = tomllib.load(f)["tool"]["uv"]["required-version"]
119
+ if not required.startswith(">="):
120
+ raise ValueError(f"[tool.uv] required-version {required!r} isn't of the form >=X.Y.Z")
121
+ match = _JUST_MIN_RE.search((root / "justfile").read_text())
122
+ if match is None:
123
+ raise ValueError("justfile has no `set minimum-version := '...'`")
124
+ # The lower bound of e.g. ">=0.13.6, <0.14".
125
+ return {UV: required.removeprefix(">=").split(",", 1)[0].strip(), JUST: match["version"]}
126
+
127
+
128
+ def dockerfile_problems(root: Path, uv: str) -> list[str]:
129
+ """Each Dockerfile uv stage whose tag isn't uv. A Dockerfile with no such
130
+ stage is a problem too, as it more likely means _DOCKER_UV_RE no longer
131
+ recognizes it; a project with no Dockerfile has nothing to check."""
132
+ dockerfile = root / "Dockerfile"
133
+ if not dockerfile.is_file():
134
+ return []
135
+ tags = [m["version"] for m in _DOCKER_UV_RE.finditer(dockerfile.read_text())]
136
+ if not tags:
137
+ return ["Dockerfile has no FROM ghcr.io/astral-sh/uv:<version> stage"]
138
+ return [f"Dockerfile: FROM ghcr.io/astral-sh/uv:{tag}, not {uv}" for tag in tags if tag != uv]
139
+
140
+
141
+ def problems(root: Path) -> tuple[list[str], dict[tuple[str, str], int]]:
142
+ """Each pin that's missing or differs from the minimum, and how many steps
143
+ use each action. No step using one is a problem too, as it more likely
144
+ means steps() or _USES_RE no longer recognize them than that CI stopped
145
+ installing uv or just."""
146
+ want = minimums(root)
147
+ found: list[str] = []
148
+ counts = dict.fromkeys(want, 0)
149
+ for path in workflow_files(root):
150
+ text = path.read_text()
151
+ for (action, key), version in want.items():
152
+ for pin in pins(text, action, key):
153
+ counts[action, key] += 1
154
+ if pin != version:
155
+ setting = f"{key}: {pin}" if pin else f"no {key}"
156
+ found.append(f"{path.relative_to(root).as_posix()}: a {action} step has {setting}, not {version}")
157
+ found += [f"no workflow or action has a {action} step" for (action, _), count in counts.items() if not count]
158
+ found += dockerfile_problems(root, want[UV])
159
+ return found, counts
160
+
161
+
162
+ def main(root: Path = Path()) -> int:
163
+ found, counts = problems(root)
164
+ for problem in found:
165
+ print(problem, file=sys.stderr)
166
+ if found:
167
+ return 1
168
+ want = minimums(root)
169
+ uv, just = f"uv {want[UV]} in {counts[UV]} steps", f"just {want[JUST]} in {counts[JUST]} steps"
170
+ dockerfile = f", and the Dockerfile uv {want[UV]}" if (root / "Dockerfile").is_file() else ""
171
+ print(f"workflows and actions pin {uv} and {just}{dockerfile}")
172
+ return 0
173
+
174
+
175
+ def run(argv: list[str]) -> int:
176
+ argparse.ArgumentParser(prog="repoutils check-pins", description=__doc__.splitlines()[0]).parse_args(argv)
177
+ return main()