fix: harmonise API, types, reporter, and test coverage

- Remove probe_raw from package re-exports (__init__.py); callers import
  from quantumvalidator.tls_utils directly
- Correct timeout type int→float in _run_openssl, _read_server_banner,
  _probe_ssh, _probe_ftp; remove int() cast in cli.py
- Replace falsy `if starttls:` with `if starttls is not None:` in
  _build_cmd (mirrors probe_raw fix)
- Add _VALID_STARTTLS frozenset; probe_raw now raises ValueError for
  unrecognised STARTTLS modes
- Fix reporter.save_report() to write from _console, not public alias;
  rename con→console in private helpers
- Move import logging as _log to module level in constants.py; fix
  import order in __init__.py (PEP 8)
- Add --cov-fail-under=100 to pyproject.toml addopts
- Fix test_exits_2_on_missing_target, test_exits_2_on_save_error;
  add TestInfoGroups (5 tests); fix _capture helper in test_reporter.py
- Update CLAUDE.md: openssl ≥ 3.5, --notes-file release pattern,
  reporter convention, main branch URLs throughout

Author: t0kubetsu

CHANGELOG.md

@@ -9,6 +9,61 @@ Version numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
 
+### Removed
+- `__init__.py`: `probe_raw` removed from package re-exports — callers (e.g.
+  vendored copy in `mailvalidator`) import directly from `quantumvalidator.tls_utils`.
+
+### Fixed
+- `tls_utils.probe_raw`: validate `starttls` parameter against the known set of
+  openssl STARTTLS modes; raises `ValueError` for unrecognised values instead of
+  forwarding arbitrary strings to the subprocess (defence-in-depth).
+- `tls_utils.probe_raw`: docstring now enumerates all four `None`-return
+  conditions (openssl missing, invalid host/port, timeout, OSError) and documents
+  the `ValueError` raised for invalid `starttls`.
+- `tls_utils.probe_raw`: `if starttls:` guard replaced with `if starttls is not None:`
+  so a pre-validated mode is passed consistently.
+- `tls_utils._build_cmd`: `if starttls:` replaced with `if starttls is not None:`
+  for consistency with `probe_raw`.
+- `tls_utils._run_openssl`, `_read_server_banner`, `_probe_ssh`, `_probe_ftp`:
+  `timeout` type annotation corrected from `int` to `float`.
+- `cli.py`: `timeout=int(timeout)` cast removed — fractional timeouts are now
+  forwarded to `assess()` without truncation.
+- `reporter.save_report()`: fixed to write from the module-level `_console`
+  (the recording instance) rather than the public `console` alias, so saved
+  files always capture the full rendered output.
+- `reporter._print_checks_table`, `reporter._print_verdict_panel`: renamed
+  parameter `con` to `console` for consistency with public API.
+- `constants.py`: `import logging as _log` moved to module-level import block;
+  was previously declared inside an `except Exception:` handler.
+- `__init__.py`: `import logging as _logging` moved before the `try/except`
+  block (PEP 8 — all imports must precede non-import statements).
+- `tests/test_tls_utils.py`: `test_returns_none_on_timeout` and
+  `test_returns_none_on_oserror` now monkeypatch `check_openssl` so they exercise
+  the subprocess error path deterministically regardless of whether `openssl` is
+  installed on the test machine.
+- `tests/test_tls_utils.py`: extracted `cmd_capture` pytest fixture in
+  `TestProbeRaw` to replace repeated `captured = {}` / `fake_run` boilerplate
+  across nine tests; fixture also mocks `check_openssl` for portability.
+- `tests/test_cli.py`: `test_exits_2_on_invalid_protocol` renamed to
+  `test_exits_2_on_missing_target` and rewritten to invoke `check` with no
+  argument (Typer exit 2) rather than testing a non-existent protocol flag.
+- `tests/test_cli.py`: `test_exits_2_on_save_error` no longer mocks
+  `pathlib.Path.write_text`; relies on a genuinely non-writable path so the
+  OSError reaches the CLI handler naturally.
+- `tests/test_reporter.py`: `_capture` helper now passes the console via
+  `console=con` keyword argument instead of positional, matching the updated
+  reporter signature.
+
+### Added
+- `tls_utils._VALID_STARTTLS` frozenset — canonical set of modes accepted by
+  `openssl s_client -starttls`; used to validate `probe_raw`'s `starttls`
+  parameter.
+- `pyproject.toml`: `--cov-fail-under=100` added to `addopts` — 100% coverage
+  is now enforced by the test runner.
+- `tests/test_cli.py`: `TestInfoGroups` class with 5 tests covering the
+  `info groups` subcommand (exit code, TLS group names, SSH group names,
+  panel headers). 252 tests total.
+
 ---
 
 ## [0.6.1] — 2026-06-24

CLAUDE.md

@@ -7,7 +7,7 @@
 | Language | Python | ≥ 3.11 |
 | CLI framework | Typer | ≥ 0.12 |
 | Terminal output | Rich | ≥ 13.7 |
-| TLS probe | openssl binary | ≥ 3.0 (external, must be on PATH) |
+| TLS probe | openssl binary | ≥ 3.5 (external, must be on PATH) |
 | Testing | pytest + pytest-cov | ≥ 8 / ≥ 5 |
 
 ## Build & Run
@@ -68,7 +68,7 @@ Two mock targets in tests:
 - **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_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`
+- **Reporter tests**: use `Console(file=StringIO(), no_color=True, width=200)` to capture output; pass `console=con` as a keyword argument — all reporter functions (public and private) accept `console=`
 - **Test class naming**: `class TestFeatureName:`, snake_case methods, AAA structure
 - **Coverage target**: 100% — enforced via `pyproject.toml` addopts
 
@@ -135,10 +135,8 @@ Every version bump **must** be followed by a GitHub release. Do not leave a vers
 git tag vX.Y.Z
 git push origin vX.Y.Z
 
-# Create the GitHub release
-gh release create vX.Y.Z \
-  --title "vX.Y.Z" \
-  --notes "$(cat <<'EOF'
+# Create the GitHub release (always use --notes-file, never inline --notes heredoc)
+cat > /tmp/release_notes.md << 'ENDOFFILE'
 ## What's changed
 
 <Copy the ### Added / ### Changed / ### Fixed / ### Removed blocks verbatim
@@ -156,9 +154,9 @@ output-format changes that require user action. Omit for patch releases.>
 
 ---
 
-**Full changelog:** https://github.com/NC3-TestingPlatform/quantumvalidator/blob/master/CHANGELOG.md
-EOF
-)"
+**Full changelog:** https://github.com/NC3-TestingPlatform/quantumvalidator/blob/main/CHANGELOG.md
+ENDOFFILE
+gh release create vX.Y.Z --title "vX.Y.Z" --notes-file /tmp/release_notes.md
 ```
 
 **Release body checklist:**

README.md

@@ -12,7 +12,7 @@ $ quantumvalidator check cloudflare.com
 ```
 
 ![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue)
-![Tests](https://img.shields.io/badge/tests-246%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-247%20passing-brightgreen)
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 ![License](https://img.shields.io/badge/license-GPLv3-lightgrey)
 
@@ -297,7 +297,7 @@ pytest tests/test_tls_utils.py
 pytest tests/test_assessor.py::TestAssessHttps -v
 ```
 
-The test suite has **246 tests** and maintains **100% statement coverage**.
+The test suite has **247 tests** and maintains **100% statement coverage**.
 
 All network I/O (`openssl s_client` subprocess) is mocked at the `probe_tls` boundary —
 no test touches a real server or the internet.

pyproject.toml

@@ -64,4 +64,4 @@ dev = ["pytest>=8", "pytest-cov>=5", "pytest-mock>=3.12"]
 [tool.pytest.ini_options]
 pythonpath = ["."]
 testpaths = ["tests"]
-addopts = "--cov=quantumvalidator --cov-report=term-missing"
+addopts = "--cov=quantumvalidator --cov-report=term-missing --cov-fail-under=100"

quantumvalidator/__init__.py

@@ -1,17 +1,16 @@
 """quantumvalidator – quantum-safe cryptography assessment library."""
 
+from __future__ import annotations
+
+import logging as _logging
 from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("quantumvalidator")
 except PackageNotFoundError:  # pragma: no cover
     __version__ = "0.6.1"
 
-import logging as _logging
-
 _logging.getLogger("quantumvalidator").addHandler(_logging.NullHandler())
 del _logging
 
-from quantumvalidator.tls_utils import probe_raw as probe_raw  # noqa: F401, E402
-
-__all__ = ["__version__", "probe_raw"]
+__all__ = ["__version__"]

quantumvalidator/cli.py

@@ -65,7 +65,7 @@ def check(
         report = assess(
             target,
             port=port,
-            timeout=int(timeout),
+            timeout=timeout,
             progress_cb=None if json_output else console.print,
         )
     except RuntimeError as exc:
@@ -144,7 +144,7 @@ def main(
         raise typer.Exit()
 
 
-def _print_json(report: "QuantumReport") -> None:
+def _print_json(report: QuantumReport) -> None:
     import json
 
     out = {

quantumvalidator/constants.py

@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 import functools
+import logging as _log
 import re
 import shutil
 import subprocess as _sp
@@ -133,6 +134,5 @@ def check_openssl() -> tuple[bool, str]:
                     "Upgrade OpenSSL (e.g. apt install openssl)."
                 )
     except Exception as exc:  # pragma: no cover
-        import logging as _log
         _log.getLogger("quantumvalidator").debug("openssl version parse failed: %s", exc)
     return True, ""

quantumvalidator/reporter.py

@@ -59,7 +59,7 @@ def print_full_report(report: QuantumReport, console: Console | None = None) ->
     con.rule("[dim]End of Report[/dim]")
 
 
-def _print_checks_table(report: QuantumReport, con: Console) -> None:
+def _print_checks_table(report: QuantumReport, console: Console) -> None:
     table = Table(
         box=box.ROUNDED,
         show_header=True,
@@ -82,11 +82,11 @@ def _print_checks_table(report: QuantumReport, con: Console) -> None:
             check.reason,
         )
 
-    con.print(table)
-    con.print()
+    console.print(table)
+    console.print()
 
 
-def _print_verdict_panel(report: QuantumReport, con: Console) -> None:
+def _print_verdict_panel(report: QuantumReport, console: Console) -> None:
     colour, symbol = _VERDICT_STYLE[report.verdict]
 
     if report.verdict == Verdict.SAFE:
@@ -128,7 +128,7 @@ def _print_verdict_panel(report: QuantumReport, con: Console) -> None:
             ),
         )
 
-    con.print(
+    console.print(
         Panel(
             body,
             title=f"[bold white]Security Verdict:[/bold white] [bold {colour}]{report.verdict.value}[/bold {colour}]",
@@ -137,7 +137,7 @@ def _print_verdict_panel(report: QuantumReport, con: Console) -> None:
             padding=(0, 1),
         )
     )
-    con.print()
+    console.print()
 
 
 # ---------------------------------------------------------------------------
@@ -178,10 +178,10 @@ def save_report(path: str) -> None:
             f"Unsupported file extension {ext!r}. Use .txt, .svg, or .html."
         )
     if fmt == "svg":
-        console.save_svg(path, clear=False)
+        _console.save_svg(path, clear=False)
     elif fmt == "html":
-        console.save_html(path, clear=False)
+        _console.save_html(path, clear=False)
     else:
-        console.save_text(path, clear=False)
+        _console.save_text(path, clear=False)