Ruff Recursive Fix

Visão Geral

Use esta habilidade para impor a qualidade do código com Ruff em um fluxo de trabalho controlado e iterativo. Ela suporta:

• Limitação opcional de escopo para uma pasta específica.
• Configurações padrão do projeto de pyproject.toml.
• Invocação flexível do Ruff (uv, ruff direto, python -m ruff ou equivalente).
• Substituições opcionais de regras por execução (--select, --ignore, --extend-select, --extend-ignore).
• Correções automáticas seguras e depois inseguras.
• Revisão de diff após cada etapa de correção.
• Repetição recursiva até que as descobertas sejam resolvidas ou exijam uma decisão.
• Uso criterioso de # noqa inline apenas quando a supressão for justificada.

Entradas

Colete estas entradas antes de executar:

• target_path (opcional): pasta ou arquivo para verificar. Vazio significa todo o repositório.
• ruff_runner (opcional): prefixo explícito do comando Ruff (por exemplo, uv run, ruff, python -m ruff, pipx run ruff).
• rules_select (opcional): códigos de regras separados por vírgula para impor.
• rules_ignore (opcional): códigos de regras separados por vírgula para ignorar.
• extend_select (opcional): regras extras para adicionar sem substituir os padrões configurados.
• extend_ignore (opcional): regras ignoradas extras sem substituir os padrões configurados.
• allow_unsafe_fixes (padrão: true): se deve executar correções inseguras do Ruff.
• ask_on_ambiguity (padrão: true): sempre perguntar ao usuário quando múltiplas escolhas válidas existirem.

Construção de Comando

Construa comandos Ruff a partir das entradas.

0. Resolver Runner Ruff

Determine um prefixo ruff_cmd reutilizável antes de construir comandos.

Ordem de resolução:

1. Se ruff_runner for fornecido, use-o como está.
2. Caso contrário, se uv estiver disponível e o Ruff for gerenciado através de uv, use uv run ruff.
3. Caso contrário, se ruff estiver disponível em PATH, use ruff.
4. Caso contrário, se o Python estiver disponível e o Ruff estiver instalado nesse ambiente, use python -m ruff.
5. Caso contrário, use qualquer equivalente específico do projeto que invoque o Ruff instalado (por exemplo, pipx run ruff), ou pare e pergunte ao usuário.

Use o mesmo ruff_cmd resolvido para todos os comandos check e format no fluxo de trabalho.

Comando base:

<ruff_cmd> check

Comando do formatador:

<ruff_cmd> format

Com alvo opcional:

<ruff_cmd> format <target_path>

Adicionar alvo opcional:

<ruff_cmd> check <target_path>

Adicionar substituições opcionais conforme necessário:

--select <codes>
--ignore <codes>
--extend-select <codes>
--extend-ignore <codes>

Exemplos:

# Full project with defaults from pyproject.toml
ruff check

# One folder with defaults
python -m ruff check src/models

# Override to skip docs and TODO-like rules for this run
uv run ruff check src --extend-ignore D,TD

# Check only selected rules in a folder
ruff check src/data --select F,E9,I

Fluxo de Trabalho

1. Análise de Linha de Base

1. Execute <ruff_cmd> check com o escopo e opções selecionados.
2. Classifique as descobertas por tipo:
   • Correção automática segura.
   • Correção automática insegura.
   • Não corrigível automaticamente.
3. Se nenhuma descoberta permanecer, pare.

2. Etapa de Correção Automática Segura

1. Execute o Ruff com --fix usando o mesmo escopo/opções.
2. Revise cuidadosamente o diff resultante quanto à correção semântica e consistência de estilo.
3. Execute <ruff_cmd> format no mesmo escopo.
4. Reexecute <ruff_cmd> check para atualizar as descobertas restantes.

3. Etapa de Correção Automática Insegura

Execute apenas se houver descobertas restantes e allow_unsafe_fixes=true.

1. Execute o Ruff com --fix --unsafe-fixes usando o mesmo escopo/opções.
2. Revise cuidadosamente o diff resultante, priorizando edições sensíveis ao comportamento.
3. Execute <ruff_cmd> format no mesmo escopo.
4. Reexecute <ruff_cmd> check.

4. Etapa de Remediação Manual

Para descobertas restantes:

1. Corrija diretamente no código quando houver uma correção clara e segura.
2. Mantenha as edições mínimas e locais.
3. Execute <ruff_cmd> format no mesmo escopo.
4. Reexecute <ruff_cmd> check.

5. Política de Ambiguidade

Se houver múltiplas soluções válidas em qualquer etapa, sempre pergunte ao usuário antes de prosseguir. Não escolha silenciosamente entre opções equivalentes.

6. Decisão de Supressão (# noqa)

Use a supressão apenas quando todas as condições forem verdadeiras:

• A regra entra em conflito com o comportamento exigido, API pública, convenções de framework ou objetivos de legibilidade.
• Refatoração seria desproporcional ao valor da regra.
• A supressão é restrita e específica (linha única, código explícito quando possível).

Diretrizes:

• Prefira # noqa: <RULE> em vez de # noqa amplo.
• Adicione um breve comentário de motivo para supressões não óbvias.
• Se dois ou mais resultados válidos existirem, sempre pergunte ao usuário qual opção prefere.

…