ruff.toml

target-version = "py315"
preview = true
line-length = 180

[lint]
select = [
  "F",   # Pyflakes
  "E",   # Pycodestyle Error
  "W",   # Pycodestyle Warning
  "UP",  # Pyupgrade
  "B",   # Bugbear
  "SIM", # Simplify
  "I",   # Isort
  "RET", # Return (Guard clauses)
  "FBT", # Boolean Trap
  "C4",  # Comprehensions
  # "ANN",  # Annotations (No Any)
  "ERA",     # Eradicate (Commented-out code)
  "PIE",     # Pie
  "PLR",     # Pylint Refactor
  "PLE",     # Pylint Error
  "EM",      # Error Message (Enforce variables for strings),
  "TD006",
  "TID251",  # Tidy-imports banned-api
  "SLF",     # flake8-self — no _-private member access across an object boundary
  "ANN401",  # No Any in annotations
  "RUF013",  # Implicit Optional banned — a required value is T, not T | None
  "TRY002",  # No raise of a vanilla Exception — raise a typed error
  "TRY004",  # Prefer TypeError for a failed type-check
  "BLE001",  # No blind except Exception — narrow it or pin a true boundary
  "RUF008",  # No mutable dataclass default
  "RUF009",  # No function-call dataclass default
  "RUF012",  # Mutable class attribute needs ClassVar
  "RUF100",  # Unused noqa — every suppression must be load-bearing
  "PT011",   # pytest.raises requires match= to pin the error
  "B018",    # No floating/unassigned string-literal or useless expression-statement
  "ISC001",  # No single-line implicit string concatenation — the forgotten-comma footgun
  "ISC002",  # No multi-line implicit string concatenation. ISC003 deliberately omitted — it pushes implicit concat, the inverse of the explicit-join rule
  "PTH",     # pathlib over os.path / open
  "PERF",    # comprehension / values() / extend over a manual accumulation loop
  "PLW0603", # No global statement — encapsulate shared mutable state
  "DTZ",     # tz-aware datetime only — a naive datetime is an unstated-timezone defect
  "N818",    # Exception class names end in Error
  "S105",    # No hardcoded password string
  "S106",    # No hardcoded password as a func arg
]

ignore = [
  "ARG",     # creates too many false positive :( (esp. on method overwrites)
  "D",       # No docstrings
  "RET504",  # Allow variable assignment before return (Debuggable)
  "B028",    # changes code behavior
  "FBT001",  # might be a bit too pedantic
  "PLR0913", # click commands legitimately take one parameter per option
  "PLR0917", # same as PLR0913
  "EM102",
  "EM101",   # too verbose, esp. with AI code generation
  "PLR2004", # too strict
]

# see: https://github.com/astral-sh/ruff/issues/22620#issue-3821861117
extend-unsafe-fixes = [
  "F401", # unused import — alert, never silently auto-remove: agentic tools work from stale in-memory copies and don't re-read a file after `ruff format`/`--fix` rewrites it, so a silently-removed import leaves them editing against a vanished line; a lint error surfaces the gap instead
  "F541", # f"Hello {name}" intended, but f"Hello name" written, would be "fixed" into "Hello name"
]

[lint.isort]
combine-as-imports = true
lines-after-imports = 2

[lint.flake8-annotations]
# Forbid 'Any' for regular args (ANN401), but allow for variadic pass-throughs
allow-star-arg-any = true

[lint.flake8-unused-arguments]
# Support the underscore approach for forced API/Inheritance arguments
ignore-variadic-names = true

[lint.flake8-bugbear]
extend-immutable-calls = [
  "click.option",
]

[lint.flake8-tidy-imports.banned-api]
"os.environ".msg = "read env at a composition root (the CLI entry) and inject it downward. Pin a genuine boundary read with a # noqa: TID251 at the line."
"os.getenv".msg = "read env at a composition root (the CLI entry) and inject it downward. Pin a genuine boundary read with a # noqa: TID251 at the line."
"builtins.input".msg = "prompt through the rich-click / beaupy CLI layer, never bare input()."
"getpass".msg = "do not import getpass — prompt for secrets through the CLI layer."
"getpass.getpass".msg = "prompt for secrets through the CLI layer, never getpass.getpass."
"getpass.getuser".msg = "ambient user identity is an env read — inject it from the composition root. Pin a genuine boundary read with a # noqa: TID251 at the line."

[lint.per-file-ignores]
"**/tests/**" = [
  "TID251",
]

[format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false