chore(utils): relax GitHub PAT validation (#380)

* Drop `InvalidGitHubTokenError`
* `validate_github_token` now emits a `UserWarning` instead of raising
* Update tests to:
  * assert no warnings for valid tokens (via `recwarn`)
  * expect `UserWarning` for malformed tokens
* Reduces false-positives and is future-proof if GitHub introduces new token formats

Closes #380

Author: filipchristiansen

src/gitingest/utils/exceptions.py

@@ -36,14 +36,3 @@ class InvalidNotebookError(Exception):
 
     def __init__(self, message: str) -> None:
         super().__init__(message)
-
-
-class InvalidGitHubTokenError(ValueError):
-    """Exception raised when a GitHub Personal Access Token is malformed."""
-
-    def __init__(self) -> None:
-        msg = (
-            "Invalid GitHub token format. To generate a token, go to "
-            "https://github.com/settings/tokens/new?description=gitingest&scopes=repo."
-        )
-        super().__init__(msg)

src/gitingest/utils/git_utils.py

@@ -6,6 +6,7 @@
 import base64
 import os
 import re
+import warnings
 from typing import Final
 from urllib.parse import urlparse
 
@@ -19,7 +20,6 @@
 )
 
 from gitingest.utils.compat_func import removesuffix
-from gitingest.utils.exceptions import InvalidGitHubTokenError
 
 # GitHub Personal-Access tokens (classic + fine-grained).
 #   - ghp_ / gho_ / ghu_ / ghs_ / ghr_  → 36 alphanumerics
@@ -319,11 +319,11 @@ def validate_github_token(token: str) -> None:
     token : str
         GitHub personal access token (PAT) for accessing private repositories.
 
-    Raises
-    ------
-    InvalidGitHubTokenError
-        If the token format is invalid.
-
     """
     if not re.fullmatch(_GITHUB_PAT_PATTERN, token):
-        raise InvalidGitHubTokenError
+        warnings.warn(
+            "Invalid GitHub token format. To generate a token, go to "
+            "https://github.com/settings/tokens/new?description=gitingest&scopes=repo.",
+            UserWarning,
+            stacklevel=2,
+        )

tests/test_git_utils.py

@@ -11,7 +11,6 @@
 
 import pytest
 
-from gitingest.utils.exceptions import InvalidGitHubTokenError
 from gitingest.utils.git_utils import (
     create_git_auth_header,
     create_git_command,
@@ -37,10 +36,10 @@
         "gho_" + "E" * 36,
     ],
 )
-def test_validate_github_token_valid(token: str) -> None:
-    """validate_github_token should accept properly-formatted tokens."""
-    # Should not raise any exception
+def test_validate_github_token_valid(token: str, recwarn: pytest.WarningsRecorder) -> None:
+    """``validate_github_token`` should silently accept well-formed tokens."""
     validate_github_token(token)
+    assert not recwarn, "validate_github_token should not warn on valid tokens"
 
 
 @pytest.mark.parametrize(
@@ -54,9 +53,10 @@ def test_validate_github_token_valid(token: str) -> None:
         "",  # Empty string
     ],
 )
-def test_validate_github_token_invalid(token: str) -> None:
-    """Test that ``validate_github_token`` raises ``InvalidGitHubTokenError`` on malformed tokens."""
-    with pytest.raises(InvalidGitHubTokenError):
+def test_validate_github_token_invalid_warns(token: str) -> None:
+    """Test that malformed tokens trigger a UserWarning carrying the helper message."""
+    warn_msg = "Invalid GitHub token format"
+    with pytest.warns(UserWarning, match=warn_msg):
         validate_github_token(token)