fix: add offline fallback when PyPI is unreachable

When no explicit --version is requested and PyPI is unreachable,
fall back to whatever version of the tool is already installed
locally instead of failing immediately.  This preserves the
pre-existing behavior where pre-installed tools worked offline.

Only applies when version=None (auto-detect).  When the user
specifies a specific --version, PyPI must be reachable to verify
it exists and resolve prefix matches.

Also fix EN DASH characters in test docstrings (Ruff RUF002).

New:
- _detect_installed_version() helper with version regex extraction
- 5 new tests: offline fallback (happy path, no tool, with version),
  detect installed version tests

Author: shenxianpeng

cpp_linter_hooks/util.py

@@ -56,10 +56,24 @@ def _resolve_version_from_pypi(
 
     Returns (resolved_version, error_message).  The error_message is
     suitable for displaying directly to the end user.
+
+    When PyPI is unreachable and no explicit version was requested,
+    falls back to whatever version is already installed on the host
+    so that pre-installed tools keep working offline.
     """
     latest, versions = _get_pypi_versions(tool)
 
     if not versions:
+        if user_input is None:
+            # PyPI is unreachable, but the user didn't ask for a specific
+            # version – try the locally installed tool as a fallback.
+            installed = _detect_installed_version(tool)
+            if installed:
+                LOG.info(
+                    "PyPI unreachable; using locally installed %s %s",
+                    tool, installed,
+                )
+                return installed, None
         return (
             None,
             f"Could not find any stable versions of {tool} on PyPI. "
@@ -90,6 +104,26 @@ def _resolve_version_from_pypi(
     )
 
 
+def _detect_installed_version(tool: str) -> Optional[str]:
+    """Return the version of *tool* already on PATH, or None.
+
+    Used as a fallback when PyPI is unreachable and no explicit version
+    was requested.  Extracts the version string from ``<tool> --version``
+    output (e.g. ``"clang-format version 18.1.8"`` → ``"18.1.8"``).
+    """
+    existing = shutil.which(tool)
+    if not existing:
+        return None
+    try:
+        result = subprocess.run(
+            [existing, "--version"], capture_output=True, text=True, timeout=10
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    match = re.search(r"(\d+\.\d+\.\d+(?:\.\d+)?)", result.stdout)
+    return match.group(1) if match else None
+
+
 def _is_version_installed(tool: str, version: str) -> Optional[Path]:
     """Return the tool path if the installed version matches, otherwise None."""
     existing = shutil.which(tool)

tests/test_util.py

@@ -9,6 +9,7 @@
 from cpp_linter_hooks.util import (
     _get_pypi_versions,
     _resolve_version_from_pypi,
+    _detect_installed_version,
     _is_version_installed,
     _install_tool,
     resolve_install_with_diagnostics,
@@ -153,14 +154,86 @@ def test_resolve_version_from_pypi_not_found(tool, user_input):
 
 @pytest.mark.benchmark
 def test_resolve_version_from_pypi_network_down():
-    """When PyPI is unreachable, return a user-friendly error."""
-    with patch("cpp_linter_hooks.util._get_pypi_versions", return_value=(None, [])):
+    """When PyPI is unreachable and no tool is installed, return an error."""
+    with (
+        patch("cpp_linter_hooks.util._get_pypi_versions", return_value=(None, [])),
+        patch("cpp_linter_hooks.util._detect_installed_version", return_value=None),
+    ):
         version, error = _resolve_version_from_pypi("clang-format", None)
     assert version is None
     assert "Could not find any stable versions" in error
     assert "network" in error.lower()
 
 
+@pytest.mark.benchmark
+def test_resolve_version_from_pypi_offline_fallback():
+    """When PyPI is unreachable but the tool is pre-installed, use it."""
+    with (
+        patch("cpp_linter_hooks.util._get_pypi_versions", return_value=(None, [])),
+        patch(
+            "cpp_linter_hooks.util._detect_installed_version",
+            return_value="18.1.8",
+        ),
+    ):
+        version, error = _resolve_version_from_pypi("clang-format", None)
+    assert version == "18.1.8"
+    assert error is None
+
+
+@pytest.mark.benchmark
+def test_resolve_version_from_pypi_offline_no_fallback_with_version():
+    """When PyPI is unreachable AND user specified a version, fail."""
+    with (
+        patch("cpp_linter_hooks.util._get_pypi_versions", return_value=(None, [])),
+        patch(
+            "cpp_linter_hooks.util._detect_installed_version",
+            return_value="18.1.8",
+        ),
+    ):
+        version, error = _resolve_version_from_pypi("clang-format", "20")
+    assert version is None
+    assert "Could not find any stable versions" in error
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# _detect_installed_version
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@pytest.mark.benchmark
+def test_detect_installed_version_success():
+    """Extract version from --version output."""
+
+    def patched_run(*args, **_kwargs):
+        return subprocess.CompletedProcess(
+            args, returncode=0, stdout="clang-format version 18.1.8\n"
+        )
+
+    with (
+        patch("shutil.which", return_value="/usr/bin/clang-format"),
+        patch("subprocess.run", side_effect=patched_run),
+    ):
+        version = _detect_installed_version("clang-format")
+    assert version == "18.1.8"
+
+
+@pytest.mark.benchmark
+def test_detect_installed_version_not_found():
+    with patch("shutil.which", return_value=None):
+        version = _detect_installed_version("clang-format")
+    assert version is None
+
+
+@pytest.mark.benchmark
+def test_detect_installed_version_subprocess_error():
+    with (
+        patch("shutil.which", return_value="/usr/bin/clang-format"),
+        patch("subprocess.run", side_effect=OSError),
+    ):
+        version = _detect_installed_version("clang-format")
+    assert version is None
+
+
 # ═══════════════════════════════════════════════════════════════════════
 # _is_version_installed
 # ═══════════════════════════════════════════════════════════════════════