lint:explain

Command /lint:explain

Explain a ruff error and show the PROPER solution. NEVER suggest # noqa!

Instructions

Step 1: Determine Input Type

The user may specify:

• Rule code: E501, F401, B008
• Path with line number: src/main.py:15
• Rule code + path: E501 src/main.py:15

Step 2: Get Error Information

ruff rule {{ error_code }}

If a file is specified, read the context:

ruff check {{ file_path }} --output-format=json

Step 3: Explain the Error

For each error explain:

1. What it means - in plain language
2. Why it's bad - real consequences
3. How to fix - concrete example

Step 4: Show Solution

CRITICAL: Always show the proper solution, not # noqa!

Solution Database for Popular Errors

E501: Line too long

# Bad
result = some_function(very_long_argument_name, another_long_argument, yet_another_one, and_more)

# Good - use parentheses for line breaks
result = some_function(
    very_long_argument_name,
    another_long_argument,
    yet_another_one,
    and_more,
)

# For strings - use concatenation or textwrap
message = (
    "This is a very long message that would exceed "
    "the line length limit if written on one line"
)

F401: Unused import

# Bad
from typing import List, Dict, Optional  # Dict is not used

# Good - remove unused import
from typing import List, Optional

# If import is needed for re-export:
from .models import User as User  # explicit re-export via `as`
# or add to __all__
__all__ = ["User"]

F841: Local variable assigned but never used

# Bad
def process():
    result = expensive_calculation()  # result is not used
    return True

# Good - use underscore to explicitly ignore
def process():
    _ = expensive_calculation()  # explicitly show result is not needed
    return True

# Or remove the assignment if result is not needed
def process():
    expensive_calculation()
    return True

B008: Do not perform function calls in argument defaults

# Bad
def process(items: list = []):  # mutable default!
    items.append(1)
    return items

# Good - use None and check
def process(items: list | None = None):
    if items is None:
        items = []
    items.append(1)
    return items

# For FastAPI Depends - this is normal, add to ignore:
# [tool.ruff.lint.per-file-ignores]
# "src/*/routers.py" = ["B008"]