ruff.toml

# 🔥 Sacred Ruff Configuration - The Divine Linting Commandments! ⚡
# Enforces code quality, catches deprecations, and prevents future regressions

# Set maximum line length (increased for practical development)
line-length = 120

# Set target Python version
target-version = "py312"

[lint]
# Select aggressive rule set for maximum code quality
select = [
    "E",    # pycodestyle errors (comprehensive style checking)
    "W",    # pycodestyle warnings (style warnings)
    "F",    # Pyflakes (logical errors, unused imports, etc.)
    "UP",   # pyupgrade (modernization, catches deprecated patterns)
    "B",    # flake8-bugbear (likely bugs and design problems)
    "SIM",  # flake8-simplify (code simplification)
    "I",    # isort (import sorting)
    "N",    # pep8-naming (naming conventions)
    "D",    # pydocstyle (docstring conventions)
    "S",    # flake8-bandit (security issues)
    "C4",   # flake8-comprehensions (better comprehensions)
    "DTZ",  # flake8-datetimez (timezone awareness)
    "T20",  # flake8-print (prevent print statements)
    "PT",   # flake8-pytest-style (pytest best practices)
    "RET",  # flake8-return (return statement improvements)
    "SLF",  # flake8-self (private member access)
    "ARG",  # flake8-unused-arguments (unused function arguments)
    "PIE",  # flake8-pie (miscellaneous improvements)
    "PL",   # Pylint (comprehensive code analysis)
    "RUF",  # Ruff-specific rules (additional checks)
]

# Ignore specific rules that conflict with our coding style
ignore = [
    "D100", # Missing docstring in public module
    "D101", # Missing docstring in public class
    "D102", # Missing docstring in public method
    "D103", # Missing docstring in public function
    "D104", # Missing docstring in public package
    "D105", # Missing docstring in magic method
    "D107", # Missing docstring in __init__
    "D203", # 1 blank line required before class docstring (conflicts with D211)
    "D213", # Multi-line docstring summary should start at the second line (conflicts with D212)
    "S101", # Use of assert detected (needed for tests)
    "T201", # print found (needed for debugging)
    "PLR0913", # Too many arguments to function call (sometimes necessary)
    "PLR0915", # Too many statements (sometimes necessary)
    "N999", # Invalid module name (allow our special naming)
    "B008", # Do not perform function calls in argument defaults (FastAPI dependencies)
    "S608", # Possible SQL injection via string concatenation (false positives)
    "RET504", # Unnecessary variable assignment before return (sometimes clearer)
    "PLR2004", # Magic values in comparisons (sometimes clearer inline)
    "E501", # Line too long (handled by formatter for most cases)
    "S603", # subprocess calls are needed for MCP client testing
    "S607", # Starting process with partial path is fine in controlled environments
    "E722", # Bare except sometimes needed for broad error catching
    "PLR0912", # Complex functions sometimes unavoidable
    "S113", # Requests without timeout in tests
    "S501", # verify=False needed for local testing
]

# Files to exclude from linting
exclude = [
    ".git",
    "__pycache__",
    ".venv",
    ".env",
    "build",
    "dist",
    "*.egg-info",
    ".pytest_cache",
    ".coverage",
    "htmlcov",
    "docs/_build",
    "logs",
    "reports",
]

[lint.per-file-ignores]
# Context-aware configuration for different script types
# More specific patterns take precedence over general ones
# Test files can have additional freedoms
"tests/**/*.py" = [
    "S101",    # Allow assert in tests
    "PLR2004", # Allow magic values in tests
    "S106",    # Allow hardcoded passwords in tests
    "S105",    # Allow hardcoded passwords/tokens in tests
    "ARG001",  # Allow unused function arguments in fixtures
    "ARG002",  # Allow unused method arguments in test fixtures
    "PLR0913", # Allow many arguments in test functions
    "B018",    # Allow useless expressions in tests (for assertions)
    "PLC0415", # Allow imports inside functions for test isolation
    "D205",    # Allow flexible docstring formatting in tests
    "D415",    # Allow flexible docstring punctuation in tests
    "E402",    # Allow imports after docstrings in test files
    "PT018",   # Allow combined assertions for clarity
    "S608",    # Allow SQL-like string operations in tests
    "PLW2901", # Allow overwriting loop variables
    "N818",    # Exception names don't need Error suffix in tests
    "PT019",   # Allow fixtures without values as parameters when they need dependencies
]

# Debug scripts have special requirements for debugging and exploration
"scripts/debug_*.py" = [
    "T201",    # Allow print in scripts
    "PLR0912", # Allow complex logic in scripts
    "PLR0915", # Allow many statements in scripts
    "D100",    # Allow missing module docstring in scripts
    "PLC0415", # Allow imports inside functions in scripts
    "S105",    # Allow hardcoded passwords/tokens
    "S108",    # Allow temporary file usage - needed for debugging
    "S110",    # Allow try-except-pass for exploration
    "N806",    # Allow uppercase variables - they represent configuration constants
    "PLW2901", # Allow overwriting loop variables
    "ARG001",  # Allow unused arguments
    "RUF001",  # Allow Unicode information symbols
    "B007",    # Allow unused loop variables
]

# Fix/migration scripts often have meta-programming patterns
"scripts/fix_*.py" = [
    "T201",    # Allow print in scripts
    "PLR0912", # Allow complex logic in scripts
    "PLR0915", # Allow many statements in scripts
    "D100",    # Allow missing module docstring in scripts
    "PLC0415", # Allow imports inside functions in scripts
    "PLR1730", # Allow if not x == y in scripts
    "S110",    # Allow try-except-pass
    "B023",    # Allow function definitions with loop variables - meta-programming pattern
    "F821",    # Allow "undefined" names - often shell variable references in strings
    "PLW2901", # Allow overwriting loop variables
    "ARG001",  # Allow unused arguments
    "RUF001",  # Allow Unicode information symbols
    "B007",    # Allow unused loop variables
]

# Run/service scripts need Docker-specific patterns
"scripts/run_*.py" = [
    "T201",    # Allow print in scripts
    "PLR0912", # Allow complex logic in scripts
    "PLR0915", # Allow many statements in scripts
    "D100",    # Allow missing module docstring in scripts
    "PLC0415", # Allow imports inside functions in scripts
    "S104",    # Allow binding to 0.0.0.0 - required for Docker containers
    "S603",    # Allow subprocess usage
    "S607",    # Allow subprocess with partial paths
    "RUF005",  # Allow list concatenation style preference
    "PLW2901", # Allow overwriting loop variables
    "ARG001",  # Allow unused arguments
]

# Other utility scripts get the baseline rules
"scripts/**/*.py" = [
    "T201",    # Allow print in scripts
    "PLR0912", # Allow complex logic in scripts
    "PLR0915", # Allow many statements in scripts
    "D100",    # Allow missing module docstring in scripts
    "PLC0415", # Allow imports inside functions in scripts
    "PLR1730", # Allow if not x == y in scripts (clearer than if x != y sometimes)
    "N802",    # Allow capitalized method names in AST visitors (visit_Call pattern)
    "SIM102",  # Allow nested if statements for clarity in complex logic
    "S105",    # Allow hardcoded passwords/tokens in test scripts
    "S110",    # Allow try-except-pass in utility scripts
    "PLW2901", # Allow overwriting loop variables
    "ARG001",  # Allow unused arguments (for future compatibility)
    "RUF001",  # Allow Unicode information symbols in output
    "B007",    # Allow unused loop variables
]

# Example and demo files need subprocess usage
"**/examples/**/*.py" = [
    "S603",    # Allow subprocess in examples
    "S607",    # Allow starting process with partial path in examples
    "T201",    # Allow print in examples
]

# CLI modules often need complex logic
"**/cli.py" = [
    "PLR0912", # Allow complex branches in CLI
    "PLR0915", # Allow many statements in CLI
    "C901",    # Allow complex functions in CLI
    "PLC0415", # Allow imports inside functions for lazy loading
    "SLF001",  # Allow private member access for internal testing
]

# Transport/protocol implementations need unused args for interface compliance
"**/transport.py" = [
    "ARG002",  # Protocol methods must match interface even if args unused
]

# Server implementations need unused args for interface compliance
"**/server.py" = [
    "ARG002",  # Handler methods must match interface signatures
]

# Allow specific patterns in __init__.py files
"**/__init__.py" = [
    "F401",    # Allow unused imports in __init__.py (re-exports)
    "D104",    # Missing docstring in public package
]

[lint.isort]
# Configure import sorting
known-first-party = ["mcp_oauth_dynamicclient", "mcp_streamablehttp_client", "mcp_streamablehttp_proxy"]
force-single-line = true
lines-after-imports = 2

[lint.pylint]
# Pylint-specific configurations
max-branches = 15
max-returns = 8
max-statements = 60

[lint.pydocstyle]
# Use Google-style docstrings
convention = "google"

# 🔥 CRITICAL: Custom rules to catch Pydantic deprecations! ⚡
[lint.flake8-bugbear]
# Catch common bugs and deprecated patterns
extend-immutable-calls = ["pydantic.BaseSettings", "pydantic_settings.BaseSettings"]

# 🔥 ULTRA-IMPORTANT: pyupgrade rules catch deprecated syntax! ⚡
[lint.pyupgrade]
# Keep up with modern Python and library practices
keep-runtime-typing = false