chore: switch to ruff + pydoclint, deprecate .gitingest, and perform a repo-wide quality sweep (#329)

* **Pre-commit**: replace `black` & `darglint` with `ruff-check` / `ruff-format`;
  add `pydoclint` for docstring quality
* **Deps**: drop `tomli`; tighten `typing_extensions`; add `eval-type-backport`;
  remove `black`, `djlint`, `pylint` from `requirements-dev`
* **Ignore files**: deprecate TOML-based `.gitingest`; introduce
  `.gitingestignore` (git-wildmatch, parsed via `_parse_ignore_file`)
* **Config**: new unified `[tool.ruff]` (lint + format + isort); delete
  `[tool.black]`, keep minimal `[tool.isort]` for now
* **Refactor/style**: adopt `from __future__ import annotations`, kw-only args,
  richer types; reorder params & `__all__`; move type-only imports under
  `if TYPE_CHECKING`; extract `_CLIArgs` `TypedDict`, migrate form data to
  `pydantic.QueryForm`; deduplicate `cli.main` / `_async_main`; use `pathlib`,
  avoid file-IO in async; replace magic numbers with constants; delete
  `is_text_file` (logic now lives in `FileSystemNode.content`)
* **Bug fix**: remove silent error in `notebook_utils._process_cell`
* **Docs**: refresh README badges
* **Tests**: update fixtures & assertions

**BREAKING**: new `.gitingestignore` file replaces (now-deprecated) `.gitingest`.

No functional API or CLI changes.

Author: filipchristiansen

.pre-commit-config.yaml

@@ -38,11 +38,6 @@ repos:
       - id: absolufy-imports
         description: "Automatically convert relative imports to absolute. (Use `args: [--never]` to revert.)"
 
-  - repo: https://github.com/psf/black
-    rev: 25.1.0
-    hooks:
-      - id: black
-
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.20.0
     hooks:
@@ -79,12 +74,18 @@ repos:
         description: "Lint markdown files."
         args: ["--disable=line-length"]
 
-  - repo: https://github.com/terrencepreilly/darglint
-    rev: v1.8.1
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.0
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+
+  - repo: https://github.com/jsh9/pydoclint
+    rev: 0.6.7
     hooks:
-      - id: darglint
-        name: darglint for source
-        args: [--docstring-style=numpy]
+      - id: pydoclint
+        name: pydoclint for source
+        args: [--style=numpy]
         files: ^src/
 
   - repo: https://github.com/pycqa/pylint
@@ -104,7 +105,6 @@ repos:
             slowapi,
             starlette>=0.40.0,
             tiktoken,
-            tomli,
             pathspec,
             uvicorn>=0.11.7,
           ]
@@ -124,7 +124,6 @@ repos:
             slowapi,
             starlette>=0.40.0,
             tiktoken,
-            tomli,
             pathspec,
             uvicorn>=0.11.7,
           ]

README.md

@@ -1,21 +1,36 @@
 # Gitingest
 
-[![Image](./docs/frontpage.png "Gitingest main page")](https://gitingest.com)
+[![Screenshot of Gitingest front page](./docs/frontpage.png)](https://gitingest.com)
 
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cyclotruc/gitingest/blob/main/LICENSE)
-[![PyPI version](https://badge.fury.io/py/gitingest.svg)](https://badge.fury.io/py/gitingest)
-[![GitHub stars](https://img.shields.io/github/stars/cyclotruc/gitingest?style=social.svg)](https://github.com/cyclotruc/gitingest)
-[![Downloads](https://pepy.tech/badge/gitingest)](https://pepy.tech/project/gitingest)
-
-[![Discord](https://dcbadge.limes.pink/api/server/https://discord.com/invite/zerRaGK9EC)](https://discord.com/invite/zerRaGK9EC)
+<!-- Badges -->
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <!-- row 1 — install & compat -->
+  <a href="https://pypi.org/project/gitingest"><img src="https://img.shields.io/pypi/v/gitingest.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/gitingest"><img src="https://img.shields.io/pypi/pyversions/gitingest.svg" alt="Python Versions"></a>
+  <br>
+  <!-- row 2 — quality & community -->
+  <a href="https://github.com/cyclotruc/gitingest/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/cyclotruc/gitingest/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/cyclotruc/gitingest"><img src="https://api.scorecard.dev/projects/github.com/cyclotruc/gitingest/badge" alt="OpenSSF Scorecard"></a>
+  <br>
+  <a href="https://github.com/cyclotruc/gitingest/blob/main/LICENSE"><img src="https://img.shields.io/github/license/cyclotruc/gitingest.svg" alt="License"></a>
+  <a href="https://pepy.tech/project/gitingest"><img src="https://pepy.tech/badge/gitingest" alt="Downloads"></a>
+  <a href="https://github.com/cyclotruc/gitingest"><img src="https://img.shields.io/github/stars/cyclotruc/gitingest" alt="GitHub Stars"></a>
+  <a href="https://discord.com/invite/zerRaGK9EC"><img src="https://img.shields.io/badge/Discord-Join_chat-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+  <br>
+  <a href="https://trendshift.io/repositories/13519"><img src="https://trendshift.io/api/badge/repositories/13519" alt="Trendshift" height="50"></a>
+</p>
+<!-- markdownlint-enable MD033 -->
 
 Turn any Git repository into a prompt-friendly text ingest for LLMs.
 
 You can also replace `hub` with `ingest` in any GitHub URL to access the corresponding digest.
 
+<!-- Extensions -->
 [gitingest.com](https://gitingest.com) · [Chrome Extension](https://chromewebstore.google.com/detail/adfjahbijlkjfoicpjkhjicpjpjfaood) · [Firefox Add-on](https://addons.mozilla.org/firefox/addon/gitingest)
 
-<!-- Keep these links. Translations will automatically update with the README. -->
+<!-- Languages -->
 [Deutsch](https://www.readme-i18n.com/cyclotruc/gitingest?lang=de) |
 [Español](https://www.readme-i18n.com/cyclotruc/gitingest?lang=es) |
 [Français](https://www.readme-i18n.com/cyclotruc/gitingest?lang=fr) |

pyproject.toml

@@ -6,16 +6,15 @@ readme = {file = "README.md", content-type = "text/markdown" }
 requires-python = ">= 3.8"
 dependencies = [
     "click>=8.0.0",
-    "fastapi[standard]>=0.109.1",  # Vulnerable to https://osv.dev/vulnerability/PYSEC-2024-38
+    "fastapi[standard]>=0.109.1",  # Minimum safe release (https://osv.dev/vulnerability/PYSEC-2024-38)
     "pydantic",
     "python-dotenv",
     "slowapi",
-    "starlette>=0.40.0",  # Vulnerable to https://osv.dev/vulnerability/GHSA-f96h-pmfr-66vw
+    "starlette>=0.40.0",  # Minimum safe release (https://osv.dev/vulnerability/GHSA-f96h-pmfr-66vw)
     "tiktoken>=0.7.0",  # Support for o200k_base encoding
-    "tomli",
     "pathspec>=0.12.1",
-    "typing_extensions; python_version < '3.10'",
-    "uvicorn>=0.11.7",  # Vulnerable to https://osv.dev/vulnerability/PYSEC-2020-150
+    "typing_extensions>= 4.0.0; python_version < '3.10'",
+    "uvicorn>=0.11.7",  # Minimum safe release (https://osv.dev/vulnerability/PYSEC-2020-150)
 ]
 
 license = {file = "LICENSE"}
@@ -62,20 +61,46 @@ disable = [
     "fixme",
 ]
 
+[tool.ruff]
+line-length = 119
+fix = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [  # https://docs.astral.sh/ruff/rules/...
+    "D107", # undocumented-public-init
+    "FIX002", # line-contains-todo
+    "TD002", # missing-todo-author
+    "PLR0913", # too-many-arguments,
+
+    # TODO: fix the following issues:
+    "TD003", # missing-todo-link, TODO: add issue links
+    "T201", # print, TODO: replace with logging
+    "S108", # hardcoded-temp-file, TODO: replace with tempfile
+    "BLE001", # blind-except, TODO: replace with specific exceptions
+    "FAST003", # fast-api-unused-path-parameter, TODO: fix
+]
+per-file-ignores = { "tests/**/*.py" = ["S101"] } # Skip the “assert used” warning
+
+[tool.ruff.lint.pylint]
+max-returns = 10
+
+[tool.ruff.lint.isort]
+order-by-type = true
+case-sensitive = true
+
 [tool.pycln]
 all = true
 
+# TODO: Remove this once we figure out how to use ruff-isort
 [tool.isort]
 profile = "black"
 line_length = 119
 remove_redundant_aliases = true
-float_to_top = true
+float_to_top = true  # https://github.com/astral-sh/ruff/issues/6514
 order_by_type = true
 filter_files = true
 
-[tool.black]
-line-length = 119
-
 # Test configuration
 [tool.pytest.ini_options]
 pythonpath = ["src"]

requirements-dev.txt

@@ -1,8 +1,6 @@
 -r requirements.txt
-black
-djlint
+eval-type-backport
 pre-commit
-pylint
 pytest
 pytest-asyncio
 pytest-mock

requirements.txt

@@ -6,5 +6,4 @@ python-dotenv
 slowapi
 starlette>=0.40.0  # Vulnerable to https://osv.dev/vulnerability/GHSA-f96h-pmfr-66vw
 tiktoken>=0.7.0  # Support for o200k_base encoding
-tomli
 uvicorn>=0.11.7  # Vulnerable to https://osv.dev/vulnerability/PYSEC-2020-150

src/gitingest/__init__.py

@@ -1,8 +1,8 @@
 """Gitingest: A package for ingesting data from Git repositories."""
 
-from gitingest.cloning import clone_repo
+from gitingest.clone import clone_repo
 from gitingest.entrypoint import ingest, ingest_async
 from gitingest.ingestion import ingest_query
-from gitingest.query_parsing import parse_query
+from gitingest.query_parser import parse_query
 
-__all__ = ["ingest_query", "clone_repo", "parse_query", "ingest", "ingest_async"]
+__all__ = ["clone_repo", "ingest", "ingest_async", "ingest_query", "parse_query"]