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/backup/__main__.py

@@ -1,9 +1,6 @@
-#!/usr/bin/env python3
-
 from __future__ import annotations
 
 from .app import main
 
-
 if __name__ == "__main__":
     raise SystemExit(main())

src/baudolo/backup/app.py

@@ -30,17 +30,13 @@ def main() -> int:
     args = parse_args()
 
     machine_id = get_machine_id()
-    backup_time = datetime.now().strftime("%Y%m%d%H%M%S")
+    # Local wall clock on purpose: generations sort by this name, and UTC would
+    # order new ones before the existing ones wherever the offset is positive.
+    backup_time = datetime.now().strftime("%Y%m%d%H%M%S")  # noqa: DTZ005
 
     versions_dir = os.path.join(args.backups_dir, machine_id, args.repo_name)
     version_dir = create_version_directory(versions_dir, backup_time)
 
-    # IMPORTANT:
-    # - keep_default_na=False prevents empty fields from turning into NaN
-    # - dtype=str keeps all columns stable for comparisons/validation
-    #
-    # Robust behavior:
-    # - if the file is missing or empty, we continue without DB dumps.
     databases_df = load_databases_df(args.databases_csv)
 
     print("💾 Start volume backups...", flush=True)
@@ -80,24 +76,29 @@ def main() -> int:
                 database_containers=args.database_containers,
             )
 
-            if args.dump_only_sql:
-                if found_db:
-                    if not dumped_any:
-                        print(
-                            f"WARNING: dump-only-sql requested but no DB dump was produced for DB volume '{volume_name}'. "
-                            "Falling back to file backup.",
-                            flush=True,
-                        )
-                    else:
-                        continue
+            if args.dump_only_sql and found_db:
+                if not dumped_any:
+                    print(
+                        f"WARNING: dump-only-sql requested but no DB dump was produced for DB volume '{volume_name}'. "
+                        "Falling back to file backup.",
+                        flush=True,
+                    )
+                else:
+                    continue
 
             live_source = get_storage_path(volume_name)
 
-            def copy(*, authoritative: bool, source: str = live_source) -> None:
+            def copy(
+                *,
+                authoritative: bool,
+                source: str = live_source,
+                volume: str = volume_name,
+                target: str = vol_dir,
+            ) -> None:
                 backup_volume(
                     versions_dir,
-                    volume_name,
-                    vol_dir,
+                    volume,
+                    target,
                     authoritative=authoritative,
                     source=source,
                 )

src/baudolo/backup/compose.py

@@ -4,10 +4,9 @@ import os
 import shutil
 import subprocess
 from pathlib import Path
-from typing import List, Optional
 
 
-def _build_compose_cmd(project_dir: str, passthrough: List[str]) -> List[str]:
+def _build_compose_cmd(project_dir: str, passthrough: list[str]) -> list[str]:
     """
     Build the compose command for this project directory.
 
@@ -30,7 +29,7 @@ def _build_compose_cmd(project_dir: str, passthrough: List[str]) -> List[str]:
     raise RuntimeError("Neither 'compose' nor 'docker' found in PATH")
 
 
-def _find_compose_file(project_dir: str) -> Optional[Path]:
+def _find_compose_file(project_dir: str) -> Path | None:
     """
     Detect a compose file in `project_dir` (case-insensitive).
 

src/baudolo/backup/db.py

@@ -1,10 +1,9 @@
 from __future__ import annotations
 
+import logging
 import os
 import pathlib
 import re
-import logging
-from typing import Optional
 
 import pandas
 
@@ -22,7 +21,7 @@ def get_instance(container: str, database_containers: list[str]) -> str:
     return re.split(r"(_|-)(database|db|postgres)", container)[0]
 
 
-def _validate_database_value(value: Optional[str], *, instance: str) -> str:
+def _validate_database_value(value: str | None, *, instance: str) -> str:
     """
     Enforce explicit database semantics:
 
@@ -70,7 +69,7 @@ def backup_database(
     container: str,
     volume_dir: str,
     db_type: str,
-    databases_df: "pandas.DataFrame",
+    databases_df: pandas.DataFrame,
     database_containers: list[str],
 ) -> bool:
     """
@@ -97,7 +96,6 @@ def backup_database(
 
         db_value = _validate_database_value(raw_db, instance=instance_name)
 
-        # Explicit: dump ALL databases
         if db_value == "*":
             if db_type != "postgres":
                 raise ValueError(
@@ -110,7 +108,6 @@ def backup_database(
             produced = True
             continue
 
-        # Concrete database dump
         db_name = db_value
         dump_file = os.path.join(out_dir, f"{db_name}.backup.sql")
 
@@ -135,7 +132,6 @@ def backup_database(
                 _atomic_write_cmd(cmd, dump_file)
                 produced = True
             except BackupException as e:
-                # Explicit DB dump failed -> hard error
                 raise BackupException(
                     f"Postgres dump failed for instance '{instance_name}', "
                     f"database '{db_name}'. This database was explicitly configured "

src/baudolo/backup/docker.py

@@ -98,5 +98,5 @@ def docker_volume_exists(volume: str) -> bool:
             f"docker volume inspect {volume} >/dev/null 2>&1 && echo OK"
         )
         return True
-    except Exception:
+    except BackupException:
         return False

src/baudolo/backup/dumps.py

@@ -15,7 +15,7 @@ def backup_mariadb_or_postgres(
     *,
     container: str,
     volume_dir: str,
-    databases_df: "pandas.DataFrame",
+    databases_df: pandas.DataFrame,
     database_containers: list[str],
 ) -> tuple[bool, bool]:
     """
@@ -34,7 +34,7 @@ def backup_mariadb_or_postgres(
     return False, False
 
 
-def _empty_databases_df() -> "pandas.DataFrame":
+def _empty_databases_df() -> pandas.DataFrame:
     """
     Create an empty DataFrame with the expected schema for databases.csv.
 
@@ -44,7 +44,7 @@ def _empty_databases_df() -> "pandas.DataFrame":
     return pandas.DataFrame(columns=["instance", "database", "username", "password"])
 
 
-def load_databases_df(csv_path: str) -> "pandas.DataFrame":
+def load_databases_df(csv_path: str) -> pandas.DataFrame:
     """
     Load databases.csv robustly.
 
@@ -74,7 +74,7 @@ def backup_dumps_for_volume(
     *,
     containers: list[str],
     vol_dir: str,
-    databases_df: "pandas.DataFrame",
+    databases_df: pandas.DataFrame,
     database_containers: list[str],
 ) -> tuple[bool, bool]:
     """