build(lint): gate make test on a clean ruff run

ruff was never wired into this repository: no target, no CI step, no pin.
It reported 45 findings across sources and tests, so nothing enforced
what the codebase already mostly followed.

Adds `make ruff` (check + format --check), `make ruff-fix`, and `make
lint` as its alias, and makes `make test` run lint as a fourth parallel
spur. The CI workflow calls `make test`, so it is covered there too. The
linter is pinned in a `lint` extra: a ruff minor bump changes which rules
fire, and with the suite gating on a clean run an unpinned linter would
fail it on an unrelated day.

The 45 findings are fixed rather than configured away. Three needed a
decision instead of the mechanical fix:

- The generation timestamp keeps its local wall clock (DTZ005 waived).
  Generations sort by that name, and UTC would order new ones before the
  existing ones wherever the offset is positive - "newest generation" is
  what every restore path selects on.
- The per-volume `copy` closure now binds volume_name and vol_dir as
  default arguments (B023). It only worked because it is called inside
  the same iteration.
- The two CLI top-level handlers keep their blind except (BLE001
  waived): turning any failure into exit 1 is what a CLI boundary is
  for. The two in run.py did not need it and were narrowed to what they
  actually catch.

Also drops the comments that restate the code: the section banners in
restore/__main__.py, the filename repeated as line 1 of nine test files,
step narration above the statement it narrates, and a block in app.py
documenting parameters that had moved to another module. What names a
trip-wire stays - the snapshot destination rule, the mysql-binary
absence in MariaDB 11 images, the session-scoped FOREIGN_KEY_CHECKS, the
spooled temp file for multi-GB dumps, and the negative control that
loses its discriminating power if it ever passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/baudolo/restore/__main__.py

@@ -34,9 +34,6 @@ def main(argv: list[str] | None = None) -> int:
     )
     sub = parser.add_subparsers(dest="cmd", required=True)
 
-    # ------------------------------------------------------------------
-    # files
-    # ------------------------------------------------------------------
     p_files = sub.add_parser("files", help="Restore files into a docker volume")
     _add_common_backup_args(p_files)
     p_files.add_argument(
@@ -49,9 +46,6 @@ def main(argv: list[str] | None = None) -> int:
         ),
     )
 
-    # ------------------------------------------------------------------
-    # postgres
-    # ------------------------------------------------------------------
     p_pg = sub.add_parser("postgres", help="Restore a single PostgreSQL database dump")
     _add_common_backup_args(p_pg)
     p_pg.add_argument("--container", required=True)
@@ -60,9 +54,6 @@ def main(argv: list[str] | None = None) -> int:
     p_pg.add_argument("--db-password", required=True)
     p_pg.add_argument("--empty", action="store_true")
 
-    # ------------------------------------------------------------------
-    # cluster
-    # ------------------------------------------------------------------
     p_cluster = sub.add_parser(
         "cluster", help="Restore a full PostgreSQL cluster dump (pg_dumpall)"
     )
@@ -81,9 +72,6 @@ def main(argv: list[str] | None = None) -> int:
     p_cluster.add_argument("--db-password", required=True)
     p_cluster.add_argument("--empty", action="store_true")
 
-    # ------------------------------------------------------------------
-    # mariadb
-    # ------------------------------------------------------------------
     p_mdb = sub.add_parser(
         "mariadb", help="Restore a single MariaDB/MySQL-compatible dump"
     )
@@ -98,8 +86,6 @@ def main(argv: list[str] | None = None) -> int:
 
     try:
         if args.cmd == "files":
-            # target volume = args.volume_name
-            # source volume (backup key) defaults to target volume
             source_volume = args.source_volume or args.volume_name
 
             bp_files = BackupPaths(
@@ -170,7 +156,7 @@ def main(argv: list[str] | None = None) -> int:
         parser.error("Unhandled command")
         return 2
 
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001 - CLI boundary: any failure becomes exit 1
         print(f"ERROR: {e}", file=sys.stderr)
         return 1
 

src/baudolo/restore/db/mariadb.py

@@ -22,11 +22,11 @@ exit 42
         if not out:
             raise RuntimeError("empty client detection output")
         return out
-    except Exception as e:
+    except Exception:
         print(
             "ERROR: neither 'mariadb' nor 'mysql' found in container.", file=sys.stderr
         )
-        raise e
+        raise
 
 
 def restore_mariadb_sql(
@@ -44,9 +44,7 @@ def restore_mariadb_sql(
         raise FileNotFoundError(sql_path)
 
     if empty:
-        # IMPORTANT:
-        # Do NOT hardcode 'mysql' here. Use the detected client.
-        # MariaDB 11 images may not contain the mysql binary at all.
+        # Do not hardcode 'mysql': MariaDB 11 images may not ship that binary.
         result = docker_exec(
             container,
             [

src/baudolo/restore/db/postgres.py

@@ -50,7 +50,6 @@ def restore_postgres_sql(
     if not os.path.isfile(sql_path):
         raise FileNotFoundError(sql_path)
 
-    # Make password available INSIDE the container for psql.
     docker_env = {"PGPASSWORD": password}
 
     if empty:

src/baudolo/restore/run.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import subprocess
 import sys
-from typing import Optional
 
 
 def run(
@@ -10,7 +9,7 @@ def run(
     *,
     stdin=None,
     capture: bool = False,
-    env: Optional[dict] = None,
+    env: dict | None = None,
 ) -> subprocess.CompletedProcess:
     try:
         kwargs: dict = {
@@ -26,21 +25,18 @@ def run(
         else:
             kwargs["stdin"] = stdin
 
-        return subprocess.run(cmd, **kwargs)
+        return subprocess.run(cmd, **kwargs)  # noqa: PLW1510 - check lives in kwargs
 
     except subprocess.CalledProcessError as e:
         msg = f"ERROR: command failed ({e.returncode}): {' '.join(cmd)}"
         print(msg, file=sys.stderr)
-        if e.stdout:
+        for stream in (e.stdout, e.stderr):
+            if not stream:
+                continue
             try:
-                print(e.stdout.decode(), file=sys.stderr)
-            except Exception:
-                print(e.stdout, file=sys.stderr)
-        if e.stderr:
-            try:
-                print(e.stderr.decode(), file=sys.stderr)
-            except Exception:
-                print(e.stderr, file=sys.stderr)
+                print(stream.decode(), file=sys.stderr)
+            except (UnicodeDecodeError, AttributeError):
+                print(stream, file=sys.stderr)
         raise
 
 
@@ -50,8 +46,8 @@ def docker_exec(
     *,
     stdin=None,
     capture: bool = False,
-    env: Optional[dict] = None,
-    docker_env: Optional[dict[str, str]] = None,
+    env: dict | None = None,
+    docker_env: dict[str, str] | None = None,
 ) -> subprocess.CompletedProcess:
     cmd: list[str] = ["docker", "exec", "-i"]
     if docker_env:
@@ -67,8 +63,8 @@ def docker_exec_sh(
     *,
     stdin=None,
     capture: bool = False,
-    env: Optional[dict] = None,
-    docker_env: Optional[dict[str, str]] = None,
+    env: dict | None = None,
+    docker_env: dict[str, str] | None = None,
 ) -> subprocess.CompletedProcess:
     return docker_exec(
         container,
@@ -85,5 +81,6 @@ def docker_volume_exists(volume: str) -> bool:
         ["docker", "volume", "inspect", volume],
         stdout=subprocess.DEVNULL,
         stderr=subprocess.DEVNULL,
+        check=False,
     )
     return p.returncode == 0