refactor: harmonization pass 2 — keyword-only assess, float timeout, print_full_report, ruff clean

- assessor: enforce keyword-only params with *,; timeout int→float; Optional→X|None
- cli: --version -v → -V; print_report→print_full_report; add info groups subcommand
- models/tls_utils: replace all Optional[X] with X|None
- reporter: print_report→print_full_report (deprecated alias kept); save_report raises ValueError
- Add pytest-mock to dev deps
- ruff: F401 cleanup in tests

Author: t0kubetsu

CLAUDE.md

@@ -34,7 +34,7 @@ quantumvalidator/
   cli.py          Typer CLI: check command; --json, --output, --version flags
   constants.py    PQC_GROUPS, SAFE_GROUPS, PROBE_GROUPS, check_openssl()
   models.py       Verdict, Status, CheckResult, QuantumReport dataclasses
-  reporter.py     print_report() — Rich terminal renderer (no I/O of its own)
+  reporter.py     print_full_report() — Rich terminal renderer (no I/O of its own)
   tls_utils.py    probe_tls() — subprocess openssl s_client; sole I/O boundary
   verdict.py      determine_verdict() / build_checks() — pure logic
 tests/
@@ -54,7 +54,7 @@ Request lifecycle:
    openssl; otherwise uses raw TLS; parses `Protocol version:` and
    `Negotiated TLS1.3 group:` from combined stdout+stderr
 5. `assess()` calls `build_checks()` and `determine_verdict()` from `verdict.py`; derives `QuantumReport`
-6. Returns `QuantumReport`; CLI calls `print_report()` from `reporter.py`
+6. Returns `QuantumReport`; CLI calls `print_full_report()` from `reporter.py`
 
 **Single I/O boundary**: all network calls go through `tls_utils.probe_tls`.
 Two mock targets in tests:
@@ -67,7 +67,7 @@ Two mock targets in tests:
 - **Fixture factory**: `make_probe_result()` in `conftest.py` — builds `TLSProbeResult` with defaults
 - **Module-level fixtures**: `SAFE_PROBE`, `UNSAFE_PROBE_CLASSICAL`, `UNSAFE_PROBE_TLS12`, `ERROR_PROBE`
 - **Assessor mocking**: patch `"quantumvalidator.assessor.check_tls"` (imported at module top)
-- **CLI mocking**: patch `"quantumvalidator.assessor.assess"` and `"quantumvalidator.reporter.print_report"` (both are lazy imports inside `check()`)
+- **CLI mocking**: patch `"quantumvalidator.assessor.assess"` and `"quantumvalidator.reporter.print_full_report"` (both are lazy imports inside `check()`)
 - **Reporter tests**: use `Console(file=StringIO(), no_color=True, width=200)` to capture output; pass console as trailing positional arg — private helpers use `con`, not `console`
 - **Test class naming**: `class TestFeatureName:`, snake_case methods, AAA structure
 - **Coverage target**: 100% — enforced via `pyproject.toml` addopts

pyproject.toml

@@ -59,7 +59,7 @@ where = ["."]
 include = ["quantumvalidator*"]
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-cov>=5"]
+dev = ["pytest>=8", "pytest-cov>=5", "pytest-mock>=3.12"]
 
 [tool.pytest.ini_options]
 pythonpath = ["."]

quantumvalidator/assessor.py

@@ -16,7 +16,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Callable, Optional
+from collections.abc import Callable
 
 from quantumvalidator.checker import check_tls
 from quantumvalidator.constants import DEFAULT_PORT_HTTPS
@@ -28,9 +28,10 @@
 
 def assess(
     target: str,
-    port: Optional[int] = None,
-    timeout: int = 10,
-    progress_cb: Optional[Callable[[str], None]] = None,
+    *,
+    port: int | None = None,
+    timeout: float = 10.0,
+    progress_cb: Callable[[str], None] | None = None,
 ) -> QuantumReport:
     """Probe *target* and assess its post-quantum TLS key exchange readiness.
 
@@ -53,7 +54,7 @@ def assess(
 
     logger.info("Starting assessment for %s:%d", target, effective_port)
 
-    result = check_tls(target, effective_port, timeout=timeout)
+    result = check_tls(target, effective_port, timeout=int(timeout))
 
     if not result.ok:
         checks: list[CheckResult] = [

quantumvalidator/cli.py

@@ -75,8 +75,8 @@ def check(
     if json_output:
         _print_json(report)
     else:
-        from quantumvalidator.reporter import print_report
-        print_report(report)
+        from quantumvalidator.reporter import print_full_report
+        print_full_report(report)
 
     if output:
         from quantumvalidator.reporter import save_report
@@ -93,10 +93,48 @@ def check(
     raise typer.Exit(code=0 if report.is_safe else 1)
 
 
+info_app = typer.Typer(name="info", help="Show reference tables.")
+app.add_typer(info_app, name="info")
+
+
+@info_app.command("groups")
+def cmd_info_groups() -> None:
+    """List all quantum-safe key exchange groups supported."""
+    from quantumvalidator.constants import PQC_GROUPS, SSH_PQC_GROUPS
+    from rich.table import Table
+    from rich.panel import Panel
+    tbl = Table(show_header=True, header_style="bold blue", padding=(0, 1))
+    tbl.add_column("Name", style="bold")
+    tbl.add_column("IANA Codepoint", style="dim")
+    tbl.add_column("Standard")
+    tbl.add_column("Safe", justify="center")
+    for name, info in PQC_GROUPS.items():
+        tbl.add_row(
+            name,
+            info.iana_codepoint or "—",
+            info.standard,
+            "[green]✔[/green]" if info.safe else "[red]✘[/red]",
+        )
+    console.print(Panel("[bold]TLS Quantum-Safe KEX Groups[/bold]", style="blue"))
+    console.print(tbl)
+    ssh_tbl = Table(show_header=True, header_style="bold blue", padding=(0, 1))
+    ssh_tbl.add_column("Name", style="bold")
+    ssh_tbl.add_column("Standard")
+    ssh_tbl.add_column("Safe", justify="center")
+    for name, info in SSH_PQC_GROUPS.items():
+        ssh_tbl.add_row(
+            name,
+            info.standard,
+            "[green]✔[/green]" if info.safe else "[red]✘[/red]",
+        )
+    console.print(Panel("[bold]SSH Quantum-Safe KEX Groups[/bold]", style="blue"))
+    console.print(ssh_tbl)
+
+
 @app.callback(invoke_without_command=True)
 def main(
     version: bool = typer.Option(
-        False, "--version", "-v", is_eager=True, help="Show version and exit."
+        False, "--version", "-V", is_eager=True, help="Show version and exit."
     ),
 ) -> None:
     if version:

quantumvalidator/models.py

@@ -9,7 +9,6 @@
 
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Optional
 
 
 class Verdict(str, Enum):
@@ -38,13 +37,13 @@ class CheckResult:
     status: Status
     """Pass / Fail / Info / Error."""
 
-    value: Optional[str]
+    value: str | None
     """Observed value (e.g. 'TLSv1.3', 'X25519MLKEM768'), or None."""
 
     reason: str
     """Human-readable explanation of the outcome."""
 
-    standard: Optional[str] = None
+    standard: str | None = None
     """Reference standard (e.g. 'CNSA 2.0, BSI TR-02102-2')."""
 
     @property
@@ -63,16 +62,16 @@ class QuantumReport:
     target: str
     """Hostname or IP that was probed."""
 
-    detected_starttls: Optional[str]
+    detected_starttls: str | None
     """STARTTLS mode detected from server banner (e.g. ``'smtp'``/``'ftp'``/``'nntp'``/``'ssh'``), or ``None`` for raw TLS."""
 
     port: int
     """TCP port used for the probe."""
 
-    tls_version: Optional[str]
+    tls_version: str | None
     """Negotiated TLS version string (e.g. 'TLSv1.3'), or None on error."""
 
-    negotiated_group: Optional[str]
+    negotiated_group: str | None
     """Negotiated key exchange name (e.g. 'X25519MLKEM768'), or None."""
 
     verdict: Verdict

quantumvalidator/reporter.py

@@ -37,7 +37,7 @@
 }
 
 
-def print_report(report: QuantumReport, console: Console | None = None) -> None:
+def print_full_report(report: QuantumReport, console: Console | None = None) -> None:
     """Render a colour-coded terminal report for *report*.
 
     :param report: Assessment report from assess().
@@ -172,10 +172,17 @@ def save_report(path: str) -> None:
     :raises OSError: If the file cannot be written.
     """
     ext = os.path.splitext(path)[1].lower()
-    fmt = _FORMAT_BY_EXT.get(ext, "text")
+    fmt = _FORMAT_BY_EXT.get(ext)
+    if fmt is None:
+        raise ValueError(
+            f"Unsupported file extension {ext!r}. Use .txt, .svg, or .html."
+        )
     if fmt == "svg":
         console.save_svg(path, clear=False)
     elif fmt == "html":
         console.save_html(path, clear=False)
     else:
         console.save_text(path, clear=False)
+
+
+print_report = print_full_report  # deprecated

quantumvalidator/tls_utils.py

@@ -14,7 +14,6 @@
 import socket
 import subprocess
 from dataclasses import dataclass, replace
-from typing import Optional
 
 from quantumvalidator.constants import (
     OPENSSL_BINARY,
@@ -59,13 +58,13 @@ class TLSProbeResult:
 
     host: str
     port: int
-    tls_version: Optional[str]
+    tls_version: str | None
     """Negotiated TLS version string (e.g. 'TLSv1.3'), or None on error."""
-    negotiated_group: Optional[str]
+    negotiated_group: str | None
     """Negotiated key-exchange group name (e.g. 'X25519MLKEM768'), or None."""
-    error: Optional[str] = None
+    error: str | None = None
     """Error message if the probe failed, None on success."""
-    detected_starttls: Optional[str] = None
+    detected_starttls: str | None = None
     """STARTTLS mode detected from server banner (e.g. ``'smtp'``/``'ftp'``/``'nntp'``/``'ssh'``), or ``None``."""
 
     @property
@@ -127,7 +126,7 @@ def probe_tls(
     return result
 
 
-def _build_cmd(host: str, port: int, starttls: Optional[str]) -> list[str]:
+def _build_cmd(host: str, port: int, starttls: str | None) -> list[str]:
     """Build the openssl s_client command list.
 
     :param host: Target hostname or IP.
@@ -157,7 +156,7 @@ def _build_cmd(host: str, port: int, starttls: Optional[str]) -> list[str]:
 def _run_openssl(
     host: str,
     port: int,
-    starttls: Optional[str],
+    starttls: str | None,
     timeout: int,
 ) -> TLSProbeResult:
     """Run a single ``openssl s_client`` probe and return the result.
@@ -424,7 +423,7 @@ def _probe_ftp(host: str, port: int, timeout: int) -> TLSProbeResult:
     return replace(_run_openssl(host, port, starttls="ftp", timeout=timeout), detected_starttls="ftp")
 
 
-def _fingerprint_banner(output: str) -> Optional[str]:
+def _fingerprint_banner(output: str) -> str | None:
     """Detect STARTTLS mode from a server's opening banner.
 
     Scans all lines for known application-protocol banner prefixes that
@@ -466,7 +465,7 @@ def _fingerprint_banner(output: str) -> Optional[str]:
     return None
 
 
-def _parse_openssl_output(output: str) -> tuple[Optional[str], Optional[str]]:
+def _parse_openssl_output(output: str) -> tuple[str | None, str | None]:
     """Parse ``openssl s_client -brief`` output.
 
     Confirmed output format (OpenSSL 3.6, 2026-04-28):
@@ -477,8 +476,8 @@ def _parse_openssl_output(output: str) -> tuple[Optional[str], Optional[str]]:
     :returns: ``(tls_version, negotiated_group)`` — either may be None.
     :rtype: tuple[str | None, str | None]
     """
-    tls_version: Optional[str] = None
-    negotiated_group: Optional[str] = None
+    tls_version: str | None = None
+    negotiated_group: str | None = None
 
     for line in output.splitlines():
         stripped = line.strip()
@@ -492,7 +491,7 @@ def _parse_openssl_output(output: str) -> tuple[Optional[str], Optional[str]]:
     return tls_version, negotiated_group
 
 
-def _extract_connection_error(output: str) -> Optional[str]:
+def _extract_connection_error(output: str) -> str | None:
     """Extract a human-readable connection error from openssl output.
 
     :param output: Combined stdout+stderr from a failed probe.

tests/test_cli.py

@@ -59,7 +59,7 @@ def _patch_assess_error(exc: Exception):
 
 
 def _patch_print_report():
-    return patch("quantumvalidator.reporter.print_report")
+    return patch("quantumvalidator.reporter.print_full_report")
 
 
 # ---------------------------------------------------------------------------
@@ -284,12 +284,12 @@ def test_output_html_creates_file(self, tmp_path):
         assert path.exists()
         assert "<html" in path.read_text().lower()
 
-    def test_output_unknown_ext_writes_plain_text(self, tmp_path):
+    def test_output_unknown_ext_exits_2(self, tmp_path):
         path = tmp_path / "report.log"
         with _patch_assess(_make_safe_report()):
             result = runner.invoke(app, ["check", "--output", str(path), "example.com"])
-        assert result.exit_code == 0
-        assert path.exists()
+        assert result.exit_code == 2
+        assert "Error" in result.output
 
     def test_short_flag_o_accepted(self, tmp_path):
         path = tmp_path / "report.txt"

tests/test_constants.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import subprocess
 
 from quantumvalidator.constants import OPENSSL_BINARY, check_openssl