uv-audit-cooldown 1.0.0__tar.gz

uv_audit_cooldown-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JGStew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uv_audit_cooldown-1.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: uv-audit-cooldown
+Version: 1.0.0
+Summary: Cooldown-aware `uv audit`: warns while a fix is inside your `exclude-newer` window, fails once it isn't.
+Keywords: uv,audit,security,supply-chain,pre-commit,github-action
+Author: JGStew
+Author-email: JGStew <admin@jgstew.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: packaging>=24
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/jgstew/uv-audit-cooldown
+Project-URL: Issues, https://github.com/jgstew/uv-audit-cooldown/issues
+Project-URL: Source, https://github.com/jgstew/uv-audit-cooldown
+Description-Content-Type: text/markdown
+
+# uv-audit-cooldown
+
+Cooldown-aware `uv audit`: it warns while a fix is inside your `exclude-newer` window, and fails once it isn't.
+
+**Unofficial, and not affiliated with Astral.** It relies on `uv audit`'s preview JSON output.
+
+```yaml
+# GitHub Action
+- uses: jgstew/uv-audit-cooldown@<full-commit-sha> # v1.0.0
+```
+
+```yaml
+# pre-commit
+repos:
+  - repo: https://github.com/jgstew/uv-audit-cooldown
+    rev: v1.0.0
+    hooks:
+      - id: uv-audit-cooldown
+        verbose: true # pre-commit hides output of passing hooks
+        stages: [manual] # needs the network
+```
+
+```sh
+uvx uv-audit-cooldown@1.0.0
+```
+
+## What it does
+
+It runs `uv audit`. For each vulnerable package it then runs
+`uv lock --dry-run --upgrade-package <name>`, which shows the newest version
+your own cooldown allows and leaves `uv.lock` untouched. If no audit
+finding is reported, no other network call is made.
+
+| Situation | Result |
+| --- | --- |
+| Every fix is still inside the cooldown | pass, with a one-line summary |
+| An upgrade is allowed, but it doesn't reach the fix yet | pass, and the summary says so |
+| A fixed version is allowed now | fail |
+| A fix is blocked by something other than the cooldown (a pin) | fail |
+| No fix has been published | fail (`--unfixed warning` to soften) |
+| No project or no `uv.lock` (as uv finds them) | pass with a warning (`--no-lockfile error` to fail) |
+
+To tell whether a fix is held back only by the cooldown, it runs a second
+dry run with the cooldown lifted. That one uses `--no-build`, so it never
+runs build code from a release that is still inside the cooldown; if it would
+need a build, the tool exits `2`.
+
+In GitHub Actions, messages are printed as `::warning`/`::error` annotations.
+`--verbose` prints one line per advisory. Other arguments go to `uv audit`,
+e.g. `--no-dev` or `--ignore GHSA-…`. Location, config, index, cache, build
+and resolver options (`--project`, `--index`, `--prerelease`, `--exclude-newer`, …)
+also go to the dry runs, so both see the same settings; `UV_*` environment
+variables reach both too. `--offline` isn't used: on a cold
+CI cache it fails, and with a stale cache it could hide a fix that is already allowed.
+
+Exit codes: `0` nothing to do now, `1` action needed, `2` uv failed or its
+output wasn't understood.
+
+## Action inputs
+
+`working-directory` (default `.`), `args` (extra `uv audit` arguments),
+`unfixed` (`error`/`warning`), `no-lockfile` (`warning`/`error`),
+`setup-uv` (`auto`/`true`/`false`), `uv-version`.
+
+## Pinning
+
+- **Action:** pin `uses:` to a commit SHA. The Action runs its own checkout
+  (`uv run --frozen --project "$GITHUB_ACTION_PATH"`) and never installs from PyPI.
+- **pre-commit:** pin `rev:` to a tag, or to a SHA with `pre-commit autoupdate --freeze`.
+- **uvx:** pin a version: `uvx uv-audit-cooldown@1.0.0`.
+
+### pre-commit limitation
+
+pre-commit installs the hook with pip (`language: python`), which ignores this
+repo's `uv.lock` and `exclude-newer`. The hook's dependency (`packaging`) and
+its build backend (`uv_build`) therefore come from PyPI at their newest allowed
+versions, with no cooldown. `rev:` pins only this repo's code. If that matters,
+use the Action (it runs `uv run --frozen` from its own lockfile), or a `local`
+hook with `language: system` and
+`entry: uvx --exclude-newer "7 days" uv-audit-cooldown@1.0.0`.
+
+## Related uv issues
+
+[astral-sh/uv#18995](https://github.com/astral-sh/uv/issues/18995),
+[astral-sh/uv#22944](https://github.com/astral-sh/uv/issues/22944),
+[astral-sh/uv#19265](https://github.com/astral-sh/uv/issues/19265),
+[astral-sh/uv#18506](https://github.com/astral-sh/uv/issues/18506)

uv_audit_cooldown-1.0.0/README.md

@@ -0,0 +1,87 @@
+# uv-audit-cooldown
+
+Cooldown-aware `uv audit`: it warns while a fix is inside your `exclude-newer` window, and fails once it isn't.
+
+**Unofficial, and not affiliated with Astral.** It relies on `uv audit`'s preview JSON output.
+
+```yaml
+# GitHub Action
+- uses: jgstew/uv-audit-cooldown@<full-commit-sha> # v1.0.0
+```
+
+```yaml
+# pre-commit
+repos:
+  - repo: https://github.com/jgstew/uv-audit-cooldown
+    rev: v1.0.0
+    hooks:
+      - id: uv-audit-cooldown
+        verbose: true # pre-commit hides output of passing hooks
+        stages: [manual] # needs the network
+```
+
+```sh
+uvx uv-audit-cooldown@1.0.0
+```
+
+## What it does
+
+It runs `uv audit`. For each vulnerable package it then runs
+`uv lock --dry-run --upgrade-package <name>`, which shows the newest version
+your own cooldown allows and leaves `uv.lock` untouched. If no audit
+finding is reported, no other network call is made.
+
+| Situation | Result |
+| --- | --- |
+| Every fix is still inside the cooldown | pass, with a one-line summary |
+| An upgrade is allowed, but it doesn't reach the fix yet | pass, and the summary says so |
+| A fixed version is allowed now | fail |
+| A fix is blocked by something other than the cooldown (a pin) | fail |
+| No fix has been published | fail (`--unfixed warning` to soften) |
+| No project or no `uv.lock` (as uv finds them) | pass with a warning (`--no-lockfile error` to fail) |
+
+To tell whether a fix is held back only by the cooldown, it runs a second
+dry run with the cooldown lifted. That one uses `--no-build`, so it never
+runs build code from a release that is still inside the cooldown; if it would
+need a build, the tool exits `2`.
+
+In GitHub Actions, messages are printed as `::warning`/`::error` annotations.
+`--verbose` prints one line per advisory. Other arguments go to `uv audit`,
+e.g. `--no-dev` or `--ignore GHSA-…`. Location, config, index, cache, build
+and resolver options (`--project`, `--index`, `--prerelease`, `--exclude-newer`, …)
+also go to the dry runs, so both see the same settings; `UV_*` environment
+variables reach both too. `--offline` isn't used: on a cold
+CI cache it fails, and with a stale cache it could hide a fix that is already allowed.
+
+Exit codes: `0` nothing to do now, `1` action needed, `2` uv failed or its
+output wasn't understood.
+
+## Action inputs
+
+`working-directory` (default `.`), `args` (extra `uv audit` arguments),
+`unfixed` (`error`/`warning`), `no-lockfile` (`warning`/`error`),
+`setup-uv` (`auto`/`true`/`false`), `uv-version`.
+
+## Pinning
+
+- **Action:** pin `uses:` to a commit SHA. The Action runs its own checkout
+  (`uv run --frozen --project "$GITHUB_ACTION_PATH"`) and never installs from PyPI.
+- **pre-commit:** pin `rev:` to a tag, or to a SHA with `pre-commit autoupdate --freeze`.
+- **uvx:** pin a version: `uvx uv-audit-cooldown@1.0.0`.
+
+### pre-commit limitation
+
+pre-commit installs the hook with pip (`language: python`), which ignores this
+repo's `uv.lock` and `exclude-newer`. The hook's dependency (`packaging`) and
+its build backend (`uv_build`) therefore come from PyPI at their newest allowed
+versions, with no cooldown. `rev:` pins only this repo's code. If that matters,
+use the Action (it runs `uv run --frozen` from its own lockfile), or a `local`
+hook with `language: system` and
+`entry: uvx --exclude-newer "7 days" uv-audit-cooldown@1.0.0`.
+
+## Related uv issues
+
+[astral-sh/uv#18995](https://github.com/astral-sh/uv/issues/18995),
+[astral-sh/uv#22944](https://github.com/astral-sh/uv/issues/22944),
+[astral-sh/uv#19265](https://github.com/astral-sh/uv/issues/19265),
+[astral-sh/uv#18506](https://github.com/astral-sh/uv/issues/18506)

uv_audit_cooldown-1.0.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "uv-audit-cooldown"
+version = "1.0.0"
+description = "Cooldown-aware `uv audit`: warns while a fix is inside your `exclude-newer` window, fails once it isn't."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = [
+    "uv",
+    "audit",
+    "security",
+    "supply-chain",
+    "pre-commit",
+    "github-action",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = ["packaging>=24"]
+
+[[project.authors]]
+name = "JGStew"
+email = "admin@jgstew.com"
+
+[project.scripts]
+uv-audit-cooldown = "uv_audit_cooldown.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jgstew/uv-audit-cooldown"
+Issues = "https://github.com/jgstew/uv-audit-cooldown/issues"
+Source = "https://github.com/jgstew/uv-audit-cooldown"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.10",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pyyaml>=6",
+    "ruff>=0.5",
+]
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["network: reaches PyPI and the OSV vulnerability service through real uv (skip with -m 'not network')"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-select = [
+    "B",
+    "I",
+    "UP",
+    "SIM",
+    "T20",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/uv_audit_cooldown/cli.py" = ["T20"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

uv_audit_cooldown-1.0.0/pyproject.toml.orig

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "uv-audit-cooldown"
+version = "1.0.0"
+description = "Cooldown-aware `uv audit`: warns while a fix is inside your `exclude-newer` window, fails once it isn't."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "JGStew", email = "admin@jgstew.com" },
+]
+requires-python = ">=3.10"
+keywords = ["uv", "audit", "security", "supply-chain", "pre-commit", "github-action"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Security",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+# uv is not a dependency: the tool drives the caller's own uv
+dependencies = [
+  "packaging>=24",
+]
+
+[dependency-groups]
+dev = [
+  "mypy>=1.10",
+  "pytest>=8",
+  "pytest-cov>=5",
+  "pyyaml>=6",
+  "ruff>=0.5",
+]
+
+[project.scripts]
+uv-audit-cooldown = "uv_audit_cooldown.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jgstew/uv-audit-cooldown"
+Issues   = "https://github.com/jgstew/uv-audit-cooldown/issues"
+Source   = "https://github.com/jgstew/uv-audit-cooldown"
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "network: reaches PyPI and the OSV vulnerability service through real uv (skip with -m 'not network')",
+]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-select = ["B", "I", "UP", "SIM", "T20"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/uv_audit_cooldown/cli.py" = ["T20"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

uv_audit_cooldown-1.0.0/src/uv_audit_cooldown/__init__.py

@@ -0,0 +1,5 @@
+"""Cooldown-aware `uv audit`."""
+
+from importlib.metadata import version
+
+__version__ = version("uv-audit-cooldown")

uv_audit_cooldown-1.0.0/src/uv_audit_cooldown/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

uv_audit_cooldown-1.0.0/src/uv_audit_cooldown/cli.py

@@ -0,0 +1,308 @@
+"""Run `uv audit`, then one `uv lock --dry-run` per vulnerable package.
+
+Exit codes: 0 nothing to do now, 1 action needed, 2 uv failed or its output was not understood.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import subprocess
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from packaging.utils import canonicalize_name
+
+from . import __version__
+from .core import (
+    Finding,
+    Kind,
+    SchemaError,
+    Severity,
+    classify,
+    cooldown_summary,
+    parse_audit,
+    reachable_versions,
+    relevant_fixes,
+)
+
+TITLE = "uv-audit-cooldown"
+AUDIT = ["audit", "--preview-features", "audit-command,json-output", "--frozen"]
+AUDIT += ["--output-format", "json", "--color", "never"]
+DRY_RUN = ["lock", "--dry-run", "--color", "never", "--upgrade-package"]
+# the probe that lifts the cooldown must not build (run code from) a release still inside it
+LIFTED = ("--exclude-newer", "false", "--no-build")
+# also passed to `uv lock`, so both commands see the same project, indexes and resolver settings
+SHARED_OPTIONS = (
+    "--directory",
+    "--project",
+    "--script",
+    "--config-file",
+    "--cache-dir",
+    "--index",
+    "--default-index",
+    "--index-url",
+    "-i",
+    "--extra-index-url",
+    "--find-links",
+    "-f",
+    "--index-strategy",
+    "--keyring-provider",
+    "--allow-insecure-host",
+    "--resolution",
+    "--prerelease",
+    "--prerelease-package",
+    "--fork-strategy",
+    "--exclude-newer",
+    "--exclude-newer-package",
+    "--no-sources-package",
+    "--no-binary-package",
+    "--no-build-package",
+    "--no-build-isolation-package",
+    "--config-setting",
+    "-C",
+    "--config-settings-package",
+)
+SHARED_FLAGS = (
+    "--no-config",
+    "--no-cache",
+    "-n",
+    "--system-certs",
+    "--no-index",
+    "--no-sources",
+    "--no-binary",
+    "--no-build",
+    "--no-build-isolation",
+    "--require-build-hashes",
+    "--no-require-build-hashes",
+)
+# uv rejects these twice, and the lifted probe sets its own
+NOT_LIFTED = ("--exclude-newer", "--exclude-newer-package", "--no-build")
+# uv's own messages for "nothing to audit here"
+NOTHING_TO_AUDIT = ("Unable to find lockfile", "No `pyproject.toml` found")
+# would make the dry runs refuse to resolve
+DROPPED_ENV = ("VIRTUAL_ENV", "UV_FROZEN", "UV_LOCKED")
+
+
+@dataclass(frozen=True)
+class RunResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+Runner = Callable[[Sequence[str], Mapping[str, str]], RunResult]
+
+
+class UvFailed(Exception):
+    pass
+
+
+class NothingToAudit(Exception):
+    pass
+
+
+def _subprocess_runner(cwd: Path) -> Runner:
+    def run(cmd: Sequence[str], env: Mapping[str, str]) -> RunResult:
+        proc = subprocess.run(
+            list(cmd),
+            cwd=cwd,
+            env=dict(env),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+        return RunResult(proc.returncode, proc.stdout, proc.stderr)
+
+    return run
+
+
+def workflow_command(level: str, message: str) -> str:
+    """A GitHub Actions annotation, with the data escaped per the runner's rules."""
+    data = message.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+    return f"::{level} title={TITLE}::{data}"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=TITLE,
+        allow_abbrev=False,
+        description=(
+            "Run `uv audit`, but warn instead of failing while an advisory's fix is still "
+            "inside the project's exclude-newer cooldown. Any other argument (or anything "
+            "after `--`) is passed to `uv audit`."
+        ),
+    )
+    parser.add_argument(
+        "--unfixed",
+        choices=[s.value for s in Severity],
+        default=Severity.ERROR.value,
+        help="how to report an advisory with no fixed version at all (default: error)",
+    )
+    parser.add_argument(
+        "--no-lockfile",
+        choices=[s.value for s in Severity],
+        default=Severity.WARNING.value,
+        help="how to report a directory with no project or no uv.lock (default: warning)",
+    )
+    parser.add_argument(
+        "--extra-args",
+        default="",
+        metavar="STRING",
+        help="more `uv audit` arguments as one shell-quoted string (used by the GitHub Action)",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="also print one line per advisory that waits on the cooldown",
+    )
+    parser.add_argument("--version", action="version", version=f"{TITLE} {__version__}")
+    return parser
+
+
+def _shared_args(args: Sequence[str]) -> list[list[str]]:
+    """The arguments `uv lock` should see too, one list per option with its value."""
+    out: list[list[str]] = []
+    short = tuple(o for o in SHARED_OPTIONS if len(o) == 2)
+    it = iter(args)
+    for arg in it:
+        if arg in SHARED_OPTIONS:
+            out.append([arg, next(it, "")])
+        elif arg in SHARED_FLAGS or arg.startswith(tuple(f"{o}=" for o in SHARED_OPTIONS)):
+            out.append([arg])
+        elif arg.startswith(short) and not arg.startswith("--"):
+            out.append([arg])  # `-iURL`
+    return out
+
+
+def _option_name(arg: list[str]) -> str:
+    return arg[0].split("=", 1)[0]
+
+
+def _flatten(args: Sequence[list[str]]) -> list[str]:
+    return [a for arg in args for a in arg]
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    runner: Runner | None = None,
+    environ: Mapping[str, str] | None = None,
+    cwd: Path | None = None,
+) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    environ = os.environ if environ is None else environ
+    cwd = Path.cwd() if cwd is None else cwd
+
+    after: list[str] = []
+    if "--" in argv:
+        split = argv.index("--")
+        argv, after = argv[:split], argv[split + 1 :]
+    opts, passthrough = _parser().parse_known_args(argv)
+    passthrough += shlex.split(opts.extra_args) + after
+    shared = _shared_args(passthrough)
+    shared_lifted = [a for a in shared if _option_name(a) not in NOT_LIFTED]
+
+    uv = environ.get("UV") or "uv"
+    env = {k: v for k, v in environ.items() if k not in DROPPED_ENV}
+    run = runner or _subprocess_runner(cwd)
+    github = bool(environ.get("GITHUB_ACTIONS"))
+
+    def emit(severity: Severity, message: str) -> None:
+        level = severity.value
+        print(workflow_command(level, message) if github else f"{level}: {message}")
+
+    try:
+        findings, adverse = _check(
+            uv,
+            passthrough,
+            _flatten(shared),
+            _flatten(shared_lifted),
+            run,
+            env,
+            Severity(opts.unfixed),
+        )
+    except NothingToAudit as exc:
+        # visible, so a missing or uncommitted lockfile does not pass unnoticed
+        severity = Severity(opts.no_lockfile)
+        emit(severity, f"nothing to audit ({exc}).")
+        return 1 if severity is Severity.ERROR else 0
+    except FileNotFoundError:
+        print(f"{TITLE}: `{uv}` not found; install uv or put it on PATH.", file=sys.stderr)
+        return 2
+    except (UvFailed, SchemaError) as exc:
+        print(f"{TITLE}: {exc}", file=sys.stderr)
+        return 2
+
+    for status in adverse:
+        emit(Severity.ERROR, f"adverse project status: {status}")
+    for f in findings:
+        if f.kind is not Kind.COOLDOWN or opts.verbose:
+            emit(f.severity, f.message)
+    summary = cooldown_summary(findings)
+    if summary:
+        emit(Severity.WARNING, summary)
+    if not findings and not adverse:
+        print(f"{TITLE}: no known vulnerabilities.")
+
+    failed = adverse or any(f.severity is Severity.ERROR for f in findings)
+    return 1 if failed else 0
+
+
+def _check(
+    uv: str,
+    passthrough: Sequence[str],
+    shared: Sequence[str],
+    shared_lifted: Sequence[str],
+    run: Runner,
+    env: Mapping[str, str],
+    unfixed: Severity,
+) -> tuple[list[Finding], tuple[object, ...]]:
+    audit = run([uv, *AUDIT, *passthrough], env)
+    if audit.returncode != 0 and not audit.stdout.strip():
+        for line in audit.stderr.splitlines():
+            if any(m in line for m in NOTHING_TO_AUDIT):
+                raise NothingToAudit(line.removeprefix("error: ").strip())
+    # uv audit exits 1 when it finds something; the JSON says what
+    if audit.returncode not in (0, 1):
+        raise UvFailed(f"`uv audit` exited {audit.returncode}:\n{audit.stderr}".rstrip())
+    try:
+        report = parse_audit(audit.stdout)
+    except SchemaError as exc:
+        raise SchemaError(f"{exc}\n{audit.stderr}".rstrip()) from None
+
+    def dry_run(name: str, *lift: str) -> str:
+        result = run([uv, *DRY_RUN, name, *lift, *(shared_lifted if lift else shared)], env)
+        if result.returncode != 0:
+            # a lifted probe that needs a build can't be decided without running that code
+            cmd = " ".join(["uv lock --dry-run --upgrade-package", name, *lift])
+            raise UvFailed(f"`{cmd}` exited {result.returncode}:\n{result.stderr}".rstrip())
+        # uv prints the changes on stderr; read both in case that moves
+        return result.stdout + result.stderr
+
+    # one dry-run per package, and one lifted probe per package, at most
+    reachable_cache: dict[tuple[str, str], tuple[str, ...] | None] = {}
+    lifted_cache: dict[tuple[str, str], tuple[str, ...] | None] = {}
+    findings = []
+    for v in report.vulnerabilities:
+        key = (canonicalize_name(v.name), v.version)
+        if not relevant_fixes(v):
+            # nothing to upgrade to, so nothing to ask uv
+            findings.append(classify(v, None, lambda: None, unfixed=unfixed))
+            continue
+        if key not in reachable_cache:
+            reachable_cache[key] = reachable_versions(dry_run(v.name), v.name, v.version)
+
+        def lifted(name: str = v.name, key: tuple[str, str] = key) -> tuple[str, ...] | None:
+            if key not in lifted_cache:
+                text = dry_run(name, *LIFTED, "--exclude-newer-package", f"{name}=false")
+                lifted_cache[key] = reachable_versions(text, name, key[1])
+            return lifted_cache[key]
+
+        findings.append(classify(v, reachable_cache[key], lifted, unfixed=unfixed))
+    return findings, report.adverse_statuses

uv_audit_cooldown-1.0.0/src/uv_audit_cooldown/core.py

@@ -0,0 +1,316 @@
+"""Parse `uv audit` JSON and `uv lock --dry-run` output, and classify findings."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from packaging.utils import canonicalize_name
+from packaging.version import InvalidVersion, Version
+
+# the only `uv audit` JSON schema version understood; anything else fails
+SCHEMA_VERSION = "preview"
+
+
+class SchemaError(Exception):
+    """uv printed something this tool does not understand. Never treated as a pass."""
+
+
+class Severity(Enum):
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class Kind(Enum):
+    COOLDOWN = "cooldown"  # a fix exists; only the cooldown keeps it out
+    FIX_ALLOWED = "fix-allowed"  # a fix is allowed now: bump
+    BLOCKED = "blocked"  # a fix exists, but something besides the cooldown holds it back
+    UNFIXED = "unfixed"  # no fix published
+    NO_APPLICABLE_FIX = "no-applicable-fix"  # every listed fix is at or below the locked version
+
+
+@dataclass(frozen=True)
+class Vulnerability:
+    name: str
+    version: str
+    id: str
+    fix_versions: tuple[str, ...]
+    link: str | None
+
+
+@dataclass(frozen=True)
+class AuditReport:
+    vulnerabilities: tuple[Vulnerability, ...]
+    adverse_statuses: tuple[Any, ...]
+
+
+@dataclass(frozen=True)
+class Finding:
+    vuln: Vulnerability
+    kind: Kind
+    severity: Severity
+    message: str
+    # newest versions the project's own cooldown allows now (None: no upgrade)
+    reachable: tuple[str, ...] | None = None
+
+
+# --- uv audit ------------------------------------------------------------------
+
+
+def _require(obj: Any, key: str, kind: type | tuple[type, ...], where: str) -> Any:
+    if not isinstance(obj, dict) or key not in obj:
+        raise SchemaError(f"uv audit JSON: {where} has no {key!r}")
+    value = obj[key]
+    if not isinstance(value, kind):
+        raise SchemaError(f"uv audit JSON: {where}.{key} is {type(value).__name__}: {value!r}")
+    return value
+
+
+def _version(text: str, where: str) -> Version:
+    try:
+        return Version(text)
+    except InvalidVersion:
+        raise SchemaError(f"uv audit JSON: {where} is not a PEP 440 version: {text!r}") from None
+
+
+def parse_audit(text: str) -> AuditReport:
+    try:
+        doc = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise SchemaError(f"uv audit did not print JSON: {exc}") from None
+    if not isinstance(doc, dict):
+        raise SchemaError(f"uv audit JSON is {type(doc).__name__}, not an object")
+
+    schema = _require(doc, "schema", dict, "document")
+    version = schema.get("version")
+    if version != SCHEMA_VERSION:
+        raise SchemaError(
+            f"uv audit JSON schema version {version!r} is not {SCHEMA_VERSION!r}; "
+            "this uv is newer than uv-audit-cooldown understands"
+        )
+
+    vulns: list[Vulnerability] = []
+    for i, raw in enumerate(_require(doc, "vulnerabilities", list, "document")):
+        where = f"vulnerabilities[{i}]"
+        dep = _require(raw, "dependency", dict, where)
+        name = _require(dep, "name", str, f"{where}.dependency")
+        ver = _require(dep, "version", str, f"{where}.dependency")
+        _version(ver, f"{where}.dependency.version")
+        fixes = _require(raw, "fix_versions", list, where)
+        for j, fix in enumerate(fixes):
+            if not isinstance(fix, str):
+                raise SchemaError(f"uv audit JSON: {where}.fix_versions[{j}] is {fix!r}")
+            _version(fix, f"{where}.fix_versions[{j}]")
+        link = raw.get("link")
+        if link is not None and not isinstance(link, str):
+            raise SchemaError(f"uv audit JSON: {where}.link is {link!r}")
+        vulns.append(
+            Vulnerability(
+                name=name,
+                version=ver,
+                id=_require(raw, "id", str, where),
+                fix_versions=tuple(fixes),
+                link=link,
+            )
+        )
+
+    adverse = _require(doc, "adverse_statuses", list, "document")
+
+    # cross-check the summary when uv gives one, so a truncated list can't pass
+    summary = doc.get("summary")
+    if isinstance(summary, dict):
+        for key, items in (("vulnerabilities", vulns), ("adverse_statuses", adverse)):
+            if key in summary and summary[key] != len(items):
+                raise SchemaError(
+                    f"uv audit JSON: summary.{key} is {summary[key]!r} "
+                    f"but {len(items)} {key} are listed"
+                )
+
+    return AuditReport(vulnerabilities=tuple(vulns), adverse_statuses=tuple(adverse))
+
+
+# --- uv lock --dry-run ---------------------------------------------------------
+
+# `Update virtualenv v21.14.11 -> v21.14.12`; a forked resolution lists several
+# versions on one side: `Update urllib3 v1.26.4 -> v2.6.3, v2.8.0`.
+_VERSIONS = r"v\S+(?:, v\S+)*"
+_CHANGE = re.compile(
+    rf"^\s*(?P<verb>Update|Add|Remove) (?P<name>\S+) (?P<old>{_VERSIONS})(?: -> (?P<new>{_VERSIONS}))?\s*$",
+    re.MULTILINE,
+)
+
+
+def _versions(group: str) -> tuple[str, ...]:
+    return tuple(v.strip().removeprefix("v") for v in group.split(","))
+
+
+def reachable_versions(text: str, name: str, version: str) -> tuple[str, ...] | None:
+    """What the dry run would move <name> to; None if it is not named (already newest)."""
+    want = canonicalize_name(name)
+    lines = []
+    for line in text.splitlines():
+        match = _CHANGE.match(line.strip())
+        if match and canonicalize_name(match["name"]) == want:
+            lines.append(match)
+    if not lines:
+        if "No lockfile changes detected" in text or _CHANGE.search(text):
+            return None
+        raise SchemaError(f"uv lock --dry-run output not understood for {name}:\n{text}".rstrip())
+
+    exact = [m for m in lines if version in _versions(m["old"])]
+    if len(exact) == 1:
+        chosen = exact[0]
+    elif len(lines) == 1 and not exact:
+        chosen = lines[0]
+    else:
+        raise SchemaError(
+            f"uv lock --dry-run names {name} more than once and none is clearly "
+            f"{version}: {[m.group(0) for m in lines]}"
+        )
+    if chosen["verb"] != "Update" or chosen["new"] is None:
+        raise SchemaError(f"uv lock --dry-run: unexpected change for {name}: {chosen.group(0)!r}")
+    return _versions(chosen["new"])
+
+
+# --- classification ------------------------------------------------------------
+
+
+def _subject(v: Vulnerability) -> str:
+    return f"{v.name} {v.version}: {v.id}"
+
+
+def _with_link(message: str, v: Vulnerability) -> str:
+    return f"{message} {v.link}" if v.link else message
+
+
+def _join(versions: Sequence[str]) -> str:
+    return ", ".join(versions)
+
+
+def relevant_fixes(v: Vulnerability) -> list[Version]:
+    """Fix versions above the locked one, lowest first (lower ones fix older branches)."""
+    current = Version(v.version)
+    return sorted(f for f in map(Version, v.fix_versions) if f > current)
+
+
+def is_fixed(version: Version, fixes: Sequence[Version]) -> bool:
+    """At or past every fix, or past a fix on its own major.minor branch."""
+    return version >= max(fixes) or any(
+        f <= version and f.release[:2] == version.release[:2] for f in fixes
+    )
+
+
+def classify(
+    v: Vulnerability,
+    reachable: tuple[str, ...] | None,
+    lifted: Callable[[], tuple[str, ...] | None],
+    *,
+    unfixed: Severity,
+) -> Finding:
+    """reachable: allowed now (None: no upgrade); lifted: reachable without the cooldown."""
+    if not v.fix_versions:
+        return Finding(
+            v,
+            Kind.UNFIXED,
+            unfixed,
+            _with_link(f"{_subject(v)} has no fixed version yet.", v),
+        )
+    fixes = relevant_fixes(v)
+    if not fixes:
+        return Finding(
+            v,
+            Kind.NO_APPLICABLE_FIX,
+            Severity.ERROR,
+            _with_link(
+                f"{_subject(v)} lists fixes {_join(v.fix_versions)}, none above the locked "
+                "version; check the advisory.",
+                v,
+            ),
+        )
+    fix_text = _join([str(f) for f in fixes])
+
+    def reaches(versions: tuple[str, ...] | None) -> list[str]:
+        return [r for r in versions or () if is_fixed(Version(r), fixes)]
+
+    hit = reaches(reachable)
+    if hit:
+        return Finding(
+            v,
+            Kind.FIX_ALLOWED,
+            Severity.ERROR,
+            _with_link(
+                f"{_subject(v)} is fixed in {fix_text}, and the cooldown allows {_join(hit)} "
+                f"now: run `uv lock --upgrade-package {v.name}`.",
+                v,
+            ),
+            reachable,
+        )
+
+    now = (
+        f"the newest version allowed now is {_join(reachable)}"
+        if reachable
+        else f"{v.version} is already the newest version allowed now"
+    )
+    without_cooldown = lifted()
+    if reaches(without_cooldown):
+        return Finding(
+            v,
+            Kind.COOLDOWN,
+            Severity.WARNING,
+            _with_link(
+                f"{_subject(v)} is fixed in {fix_text}, which is still inside the exclude-newer "
+                f"cooldown; {now}.",
+                v,
+            ),
+            reachable,
+        )
+    best = _join(without_cooldown) if without_cooldown else v.version
+    return Finding(
+        v,
+        Kind.BLOCKED,
+        Severity.ERROR,
+        _with_link(
+            f"{_subject(v)} is fixed in {fix_text}, but no fixed version is reachable even with "
+            f"the cooldown lifted (best: {best}); a version constraint is holding {v.name} back.",
+            v,
+        ),
+        reachable,
+    )
+
+
+def cooldown_summary(findings: Sequence[Finding]) -> str | None:
+    """One line for every finding that only waits on the cooldown."""
+    waiting = [f for f in findings if f.kind is Kind.COOLDOWN]
+    if not waiting:
+        return None
+    by_package: dict[tuple[str, str], list[Finding]] = {}
+    for f in waiting:
+        by_package.setdefault((f.vuln.name, f.vuln.version), []).append(f)
+
+    parts = []
+    moves = []
+    for (name, version), group in by_package.items():
+        if len(group) == 1:
+            (f,) = group
+            parts.append(f"{name} {version} ({f.vuln.id}, fixed in {relevant_fixes(f.vuln)[0]})")
+        else:
+            earliest = min(relevant_fixes(f.vuln)[0] for f in group)
+            parts.append(f"{name} {version} ({len(group)} advisories, earliest fix {earliest})")
+        if group[0].reachable:
+            moves.append(f"{name} can go to {_join(group[0].reachable)} now")
+
+    count = len(waiting)
+    head = (
+        f"{count} finding waits" if count == 1 else f"{count} findings wait"
+    ) + " on the exclude-newer cooldown: "
+    them = "it" if count == 1 else "them"
+    tail = (
+        f"{'; '.join(moves)}, which does not fix {them} yet."
+        if moves
+        else f"Nothing to do until it allows {them}."
+    )
+    return f"{head}{'; '.join(parts)}. {tail}"