chore: migrate to Ruff, deprecate .gitingest, and general code-quality sweep

* Pre-commit
  • Drop `black` + `darglint` hooks
  • Add `ruff-check` & `ruff-format` (astral-sh/ruff-pre-commit)
  • Swap `darglint` → `pydoclint` for doc-string lint/validation

* Dependencies
  • Remove `tomli`
  • Tighten `typing_extensions` pin; add `eval-type-backport`
  • `requirements-dev`: drop `black`, `djlint`, `pylint` (only used inside pre-commit virtualenv)

* Ignore handling
  • Deprecate `.gitingest` (TOML) → new `.gitingestignore` with git-wildmatch syntax
  • Delete `apply_gitingest_file`; reuse `_parse_ignore_file` shared with `.gitignore`

* Tooling / config
  • New `[tool.ruff]` section in `pyproject.toml`
  • Remove `[tool.black]`

* README
  • Refresh badges (PyPI, CI, Ruff, Discord, Trendshift)

* Codebase refactor
  • Enable `from __future__ import annotations`; add rich type hints throughout
  • Re-order function parameters and `__all__` exports for consistency
  • Move type-only imports under `if TYPE_CHECKING`
  • Extract CLI args to `TypedDict` `_CLIArgs`; form data to pydantic `QueryForm`
  • Deduplicate `cli.main` / `_async_main`
  • Split large blocks into helpers
  • Remove magic numbers → constants
  • Use `pathlib` over `os`; avoid `try/except` inside loops; no file-IO in async paths
  • Enforce kw-only args
  • Minor Ruff-driven clean-ups

* Bug fix
  • Remove silent logic bug in `notebook_utils._process_cell`

* Tests
  • Update fixtures & assertions

No functional API changes except the `.gitingestignore` addition & `.gitingest` deprecation.

Author: filipchristiansen

src/gitingest/clone.py

@@ -4,11 +4,10 @@
 
 from pathlib import Path
 from typing import TYPE_CHECKING
-from urllib.parse import urlparse
 
 from gitingest.config import DEFAULT_TIMEOUT
 from gitingest.utils.git_utils import (
-    _is_github_host,
+    is_github_host,
     check_repo_exists,
     create_git_auth_header,
     create_git_command,
@@ -53,7 +52,7 @@ async def clone_repo(config: CloneConfig, token: str | None = None) -> None:
     partial_clone: bool = config.subpath != "/"
 
     # Validate token if provided
-    if token and _is_github_host(url):
+    if token and is_github_host(url):
         validate_github_token(token)
 
     # Create parent directory if it doesn't exist
@@ -65,14 +64,8 @@ async def clone_repo(config: CloneConfig, token: str | None = None) -> None:
         raise ValueError(msg)
 
     clone_cmd = ["git"]
-    if token and _is_github_host(url):
-        # Only pass URL if it's not the default github.com to maintain backward compatibility
-
-        parsed = urlparse(url)
-        if parsed.hostname == "github.com":
-            clone_cmd += ["-c", create_git_auth_header(token)]
-        else:
-            clone_cmd += ["-c", create_git_auth_header(token, url)]
+    if token and is_github_host(url):
+        clone_cmd += ["-c", create_git_auth_header(token, url)]
 
     clone_cmd += ["clone", "--single-branch"]
     # TODO: Re-enable --recurse-submodules when submodule support is needed

src/gitingest/utils/git_utils.py

@@ -5,14 +5,15 @@
 import asyncio
 import base64
 import re
+import warnings
 from urllib.parse import urlparse
 
 from gitingest.utils.exceptions import InvalidGitHubTokenError
 
 GITHUB_PAT_PATTERN = r"^(?:github_pat_|ghp_)[A-Za-z0-9_]{36,}$"
 
 
-def _is_github_host(url: str) -> bool:
+def is_github_host(url: str) -> bool:
     """
     Check if a URL is from a GitHub host (github.com or GitHub Enterprise).
 
@@ -26,14 +27,12 @@ def _is_github_host(url: str) -> bool:
     bool
         True if the URL is from a GitHub host, False otherwise
     """
-    parsed = urlparse(url)
-    hostname = parsed.hostname or ""
+    hostname = urlparse(url).hostname or ""
     return hostname == "github.com" or hostname.startswith("github.")
 
 
 async def run_command(*args: str) -> tuple[bytes, bytes]:
-    """
-    Execute a shell command asynchronously and return (stdout, stderr) bytes.
+    """Execute a shell command asynchronously and return (stdout, stderr) bytes.
 
     Parameters
     ----------
@@ -105,7 +104,7 @@ async def check_repo_exists(url: str, token: str | None = None) -> bool:
 
     """
     expected_path_length = 2
-    if token and _is_github_host(url):
+    if token and is_github_host(url):
         return await _check_github_repo_exists(url, token=token)
 
     proc = await asyncio.create_subprocess_exec(
@@ -157,18 +156,13 @@ async def _check_github_repo_exists(url: str, token: str | None = None) -> bool:
         If the repository is not found, if the provided URL is invalid, or if the token format is invalid.
 
     """
-    m = re.match(r"https?://github\.([^/]*)/([^/]+)/([^/]+?)(?:\.git)?/?$", url)
-    if not m:
-        m = re.match(r"https?://github\.com/([^/]+)/([^/]+?)(?:\.git)?/?$", url)
-        if not m:
-            raise ValueError(f"Un-recognised GitHub URL: {url!r}")
-        owner, repo = m.groups()
+    host, owner, repo = _parse_github_url(url)
+
+    if host == "github.com":
         api = f"https://api.github.com/repos/{owner}/{repo}"
-    else:
-        _, owner, repo = m.groups()
+    else:  # GitHub Enterprise
+        api = f"https://{host}/api/v3/repos/{owner}/{repo}"
 
-        parsed = urlparse(url)
-        api = f"https://{parsed.hostname}/api/v3/repos/{owner}/{repo}"
     cmd = [
         "curl",
         "--silent",
@@ -203,6 +197,39 @@ async def _check_github_repo_exists(url: str, token: str | None = None) -> bool:
     raise RuntimeError(msg)
 
 
+def _parse_github_url(url: str) -> tuple[str, str, str]:
+    """Parse a GitHub URL and return (hostname, owner, repo).
+
+    Parameters
+    ----------
+    url : str
+        The URL of the GitHub repository to parse.
+
+    Returns
+    -------
+    tuple[str, str, str]
+        A tuple containing the hostname, owner, and repository name.
+
+    Raises
+    ------
+    ValueError
+        If the URL is not a valid GitHub repository URL.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("URL must start with http:// or https://")
+
+    if not parsed.hostname or not parsed.hostname.startswith("github."):
+        raise ValueError(f"Un-recognised GitHub hostname: {parsed.hostname!r}")
+
+    parts = parsed.path.strip("/").removesuffix(".git").split("/")
+    if len(parts) != 2:
+        raise ValueError("Path must look like /<owner>/<repo>")
+
+    owner, repo = parts
+    return parsed.hostname, owner, repo
+
+
 async def fetch_remote_branch_list(url: str, token: str | None = None) -> list[str]:
     """Fetch the list of branches from a remote Git repository.
 
@@ -223,14 +250,8 @@ async def fetch_remote_branch_list(url: str, token: str | None = None) -> list[s
     fetch_branches_command = ["git"]
 
     # Add authentication if needed
-    if token and _is_github_host(url):
-        # Only pass URL if it's not the default github.com to maintain backward compatibility
-
-        parsed = urlparse(url)
-        if parsed.hostname == "github.com":
-            fetch_branches_command += ["-c", create_git_auth_header(token)]
-        else:
-            fetch_branches_command += ["-c", create_git_auth_header(token, url)]
+    if token and is_github_host(url):
+        fetch_branches_command += ["-c", create_git_auth_header(token, url)]
 
     fetch_branches_command += ["ls-remote", "--heads", url]
 
@@ -266,32 +287,42 @@ def create_git_command(base_cmd: list[str], local_path: str, url: str, token: st
 
     """
     cmd = [*base_cmd, "-C", local_path]
-    if token and _is_github_host(url):
+    if token and is_github_host(url):
         validate_github_token(token)
         cmd += ["-c", create_git_auth_header(token, url=url)]
     return cmd
 
 
-def create_git_auth_header(token: str, url: str = "https://github.com") -> str:
+def create_git_auth_header(token: str, url: str | None = None) -> str:
     """Create a Basic authentication header for GitHub git operations.
 
     Parameters
     ----------
     token : str
         GitHub personal access token
-    url : str
+    url : str | None
         The GitHub URL to create the authentication header for.
-        Defaults to "https://github.com".
+        Defaults to "https://github.com" if not provided.
 
     Returns
     -------
     str
         The git config command for setting the authentication header
 
     """
+    if url is None:
+        # TODO: Deprecate implicit github.com URL and require passing the url
+        warnings.warn(
+            "Implicitly assuming 'github.com' as the host is deprecated and will be "
+            "removed in a future release. Explicitly pass the repository `url` to "
+            "create_git_auth_header() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        hostname = "github.com"
+    else:
+        hostname = urlparse(url).hostname
 
-    parsed = urlparse(url)
-    hostname = parsed.hostname or "github.com"
     basic = base64.b64encode(f"x-oauth-basic:{token}".encode()).decode()
     return f"http.https://{hostname}/.extraheader=Authorization: Basic {basic}"
 

tests/test_git_utils.py

@@ -13,9 +13,9 @@
 
 from gitingest.utils.exceptions import InvalidGitHubTokenError
 from gitingest.utils.git_utils import (
-    _is_github_host,
     create_git_auth_header,
     create_git_command,
+    is_github_host,
     validate_github_token,
 )
 
@@ -187,9 +187,9 @@ def test_create_git_command_helper_calls(
         ("ftp://github.com/owner/repo.git", True),  # Different protocol but still github.com
     ],
 )
-def test_is_github_host(url, expected):
-    """_is_github_host should correctly identify GitHub and GitHub Enterprise URLs."""
-    assert _is_github_host(url) == expected
+def test_is_github_host(url: str, expected: bool) -> None:
+    """Test that ``is_github_host`` correctly identifies GitHub and GitHub Enterprise URLs."""
+    assert is_github_host(url) == expected
 
 
 @pytest.mark.parametrize(
@@ -204,16 +204,16 @@ def test_is_github_host(url, expected):
         ("ghp_" + "d" * 36, "http://github.internal", "github.internal"),
     ],
 )
-def test_create_git_auth_header_with_ghe_url(token, url, expected_hostname):
-    """create_git_auth_header should handle GitHub Enterprise URLs correctly."""
+def test_create_git_auth_header_with_ghe_url(token: str, url: str, expected_hostname: str) -> None:
+    """Test that ``create_git_auth_header`` handles GitHub Enterprise URLs correctly."""
     header = create_git_auth_header(token, url)
     expected_basic = base64.b64encode(f"x-oauth-basic:{token}".encode()).decode()
     expected = f"http.https://{expected_hostname}/.extraheader=Authorization: Basic {expected_basic}"
     assert header == expected
 
 
 @pytest.mark.parametrize(
-    "base_cmd, local_path, url, token, expected_auth_hostname",
+    ("base_cmd", "local_path", "url", "token", "expected_auth_hostname"),
     [
         # GitHub.com URLs - should use default hostname
         (
@@ -247,8 +247,14 @@ def test_create_git_auth_header_with_ghe_url(token, url, expected_hostname):
         ),
     ],
 )
-def test_create_git_command_with_ghe_urls(base_cmd, local_path, url, token, expected_auth_hostname):
-    """create_git_command should handle GitHub Enterprise URLs correctly."""
+def test_create_git_command_with_ghe_urls(
+    base_cmd: list[str],
+    local_path: str,
+    url: str,
+    token: str,
+    expected_auth_hostname: str,
+) -> None:
+    """Test that ``create_git_command`` handles GitHub Enterprise URLs correctly."""
     cmd = create_git_command(base_cmd, local_path, url, token)
 
     # Should have base command and -C option
@@ -266,16 +272,21 @@ def test_create_git_command_with_ghe_urls(base_cmd, local_path, url, token, expe
 
 
 @pytest.mark.parametrize(
-    "base_cmd, local_path, url, token",
+    ("base_cmd", "local_path", "url", "token"),
     [
         # Should NOT add auth headers for non-GitHub URLs
         (["git", "clone"], "/some/path", "https://gitlab.com/owner/repo.git", "ghp_" + "a" * 36),
         (["git", "clone"], "/some/path", "https://bitbucket.org/owner/repo.git", "ghp_" + "b" * 36),
         (["git", "clone"], "/some/path", "https://git.example.com/owner/repo.git", "ghp_" + "c" * 36),
     ],
 )
-def test_create_git_command_ignores_non_github_urls(base_cmd, local_path, url, token):
-    """create_git_command should not add auth headers for non-GitHub URLs."""
+def test_create_git_command_ignores_non_github_urls(
+    base_cmd: list[str],
+    local_path: str,
+    url: str,
+    token: str,
+) -> None:
+    """Test that ``create_git_command`` does not add auth headers for non-GitHub URLs."""
     cmd = create_git_command(base_cmd, local_path, url, token)
 
     # Should only have base command and -C option, no auth headers