[CHORE]: Achieve Zero Static-Type Errors Across All Checkers (mypy, ty, pyright, pyrefly)

[crivetimihai]

🧭 Chore Summary

Run all four configured static-type checkers: make mypy pyright ty pyrefly and drive their error counts to 0 while keeping all tests green.

---

🧱 Areas Affected

• Pre-commit hooks / linters
• Build system / Make targets (make mypy, make pyright, make ty, make pyrefly, make pre-commit)
• GitHub Actions / CI pipeline
• Runtime codebase (type hints, stub packages, generics, etc.)

---

⚙️ Context / Rationale

Type checkers catch whole classes of bugs-mismatched APIs, wrong return types, None mishandling-before they hit prod. Aligning on a clean slate prevents regressions and unlocks stricter CI gates for long-term safety.

---

📦 Related Make Targets

Target	Purpose
make mypy	Run mypy static analysis
make pyright	Run pyright (strict mode)
make ty	Run ty ultra-fast checker
make pyrefly	Run pyrefly flow-sensitive checker
make pre-commit	Execute all hooks locally
make lint	Meta-target (black + isort + autoflake + pylint + type checks)
make test	Unit / integration tests
make smoketest	Minimal E2E sanity check

Bold targets are mandatory; CI must fail if any one of them reports errors.

---

📋 Acceptance Criteria

• make mypy, make pyright, make ty, and make pyrefly exit 0 with 0 errors.
• make pre-commit runs without modifying the working tree.
• make test and make smoketest pass.
• GitHub Actions enforces all of the above (e.g. --no-warn-unused-ignores, --strict, --fail-under 100 where supported).
• Changelog entry under "Maintenance".

---

🛠️ Task List (suggested flow)

1. Baseline scan

   make mypy pyright ty pyrefly > /tmp/type-report.txt

   Prioritise high-impact error classes (arg-type, bad-return, import-error, …).

2. Fast wins

   • Add / fix type annotations on obvious offenders.
   • Run autoflake → isort → black to keep imports tidy.

3. Third-party stubs

   • Install missing types-foo wheels (types-redis, types-psutil, …).
   • Mark internal packages as py.typed where appropriate.

4. Gradual tightening

   • Replace Any with precise Union / Protocol types; add generics.
   • Use typing.cast or assert isinstance() only when unavoidable.

5. Suppressions

   • Minimise # type: ignore; always cite the ignored error code.
   • Add explanatory comments for every suppression.

6. CI integration

   • Extend lint.yml (or equivalent) to run all four checkers in parallel.
   • Fail the job if any checker emits diagnostics.

7. Regression guard

   • Add a make types meta-target that wraps all checkers; invoke it from make lint and CI.

8. Local & container tests

   • make venv install install-dev test smoketest – full local pass.

   • Docker: make docker-prod docker-run-ssl-host – build prod image & run containerised smoke-tests.

   • Compose: make compose-up (Postgres + Redis) using the freshly-built :latest image; verify API health.

   • DB migrations: run Alembic upgrade/downgrade cycle.

   • Helm / minikube:

     make minikube-install minikube-start
     helm upgrade --install mcp charts/mcp-stack

   • PyPI dry-run:

     make devpi-install devpi-init devpi-start
     make devpi-upload  # build & upload wheel
     pip install --index-url http://localhost:3141/root/public mcpgateway --no-cache-dir

9. Final validation

   make lint types test smoketest

---

📖 References

• Ty – lightning-fast Rust-based checker & LSP · https://github.com/astral-sh/ty
• Pyrefly – flow-sensitive checker with IDE/CLI support · https://pyrefly.org
• Pyright – Microsoft's strict type checker & language server · https://github.com/microsoft/pyright
• Mypy – the original gradual-typing workhorse · https://github.com/python/mypy

---

🧩 Additional Notes

• If duplicate errors surface across checkers, fix once - don't blanket-suppress in each config.
• Consider enabling strict_optional = True (mypy) and strict = true (pyright) once the baseline is clean.
• Keep commits small and focused (one module or error-family per commit) to ease code review.