Pular para o conteúdo principal

search_files

A ferramenta search_files realiza buscas com regex em múltiplos arquivos do seu projeto. Ela ajuda o AI Cockpit Reasoning a localizar padrões de código, texto ou outro conteúdo específico em toda a sua base de código com resultados contextuais.

Parâmetros​

A ferramenta aceita estes parâmetros:

  • path (obrigatório): O caminho do diretório para pesquisar, relativo ao diretório de trabalho atual
  • regex (obrigatório): O padrão de expressão regular para pesquisar (usa a sintaxe de regex do Rust)
  • file_pattern (opcional): Padrão glob para filtrar arquivos (por exemplo, '*.ts' para arquivos TypeScript)

O Que Faz​

Esta ferramenta pesquisa em arquivos de um diretório especificado usando expressões regulares, mostrando cada correspondência com o contexto ao redor. É como ter um recurso poderoso de "Encontrar em Arquivos" que funciona em toda a estrutura do projeto.

Quando é usada?​

  • Quando o AI Cockpit Reasoning precisa encontrar onde funções ou variáveis específicas são usadas
  • Quando o AI Cockpit Reasoning ajuda na refatoração e precisa entender os padrões de uso
  • Quando o AI Cockpit Reasoning precisa localizar todas as instâncias de um padrão de código específico
  • Quando o AI Cockpit Reasoning pesquisa texto em vários arquivos com recursos de filtragem

Principais Características​

  • Pesquisa em vários arquivos em uma única operação usando Ripgrep de alto desempenho
  • Mostra o contexto em torno de cada correspondência (1 linha antes e depois)
  • Filtra arquivos por tipo usando padrões glob (por exemplo, apenas arquivos TypeScript)
  • Fornece números de linha para fácil referência
  • Usa padrões de regex poderosos para pesquisas precisas
  • Limita automaticamente a saída a 300 resultados com notificação
  • Trunca linhas com mais de 500 caracteres com o marcador "[truncated...]"
  • Combina inteligentemente correspondências próximas em blocos únicos para legibilidade

Limitações​

  • Funciona melhor com arquivos baseados em texto (não é eficaz para arquivos binários como imagens)
  • O desempenho pode diminuir com bases de código extremamente grandes
  • Usa a sintaxe de regex do Rust, que pode ser ligeiramente diferente de outras implementações de regex
  • Não pode pesquisar dentro de arquivos compactados ou arquivos
  • O tamanho do contexto padrão é fixo (1 linha antes e depois)
  • Pode exibir tamanhos de contexto variáveis quando as correspondências estão próximas umas das outras devido ao agrupamento de resultados

Como Funciona​

Quando a ferramenta search_files é invocada, ela segue este processo:

  1. Validação de Parâmetros: Valida os parâmetros obrigatórios path e regex
  2. Resolução de Caminho: Resolve o caminho relativo para um caminho absoluto
  3. Execução da Pesquisa:
    • Usa o Ripgrep (rg) para pesquisa de texto de alto desempenho
    • Aplica a filtragem de padrão de arquivo, se especificado
    • Coleta correspondências com o contexto ao redor
  4. Formatação do Resultado:
    • Formata os resultados com caminhos de arquivo, números de linha e contexto
    • Exibe 1 linha de contexto antes e depois de cada correspondência
    • Estrutura a saída para fácil legibilidade
    • Limita os resultados a um máximo de 300 correspondências com notificação
    • Trunca linhas com mais de 500 caracteres
    • Mescla correspondências próximas em blocos contíguos

Formato dos Resultados da Pesquisa​

Os resultados da pesquisa incluem:

  • Caminhos de arquivo relativos para cada arquivo correspondente (prefixados com #)
  • Linhas de contexto antes e depois de cada correspondência (1 linha por padrão)
  • Números de linha preenchidos com 3 espaços seguidos por | e o conteúdo da linha
  • Uma linha separadora (----) após cada grupo de correspondência

Formato de saída de exemplo:

# rel/path/to/app.ts
 11 |   // Alguma lógica de processamento aqui
 12 |   // TODO: Implementar tratamento de erros
 13 |   return processedData;
----

# Mostrando os primeiros 300 de mais de 300 resultados. Use uma pesquisa mais específica, se necessário.

Quando as correspondências ocorrem próximas umas das outras, elas são mescladas em um único bloco em vez de serem mostradas como resultados separados:

# rel/path/to/auth.ts
 13 | // Algum código aqui
 14 | // TODO: Adicionar validação adequada
 15 | function validateUser(credentials) {
 16 |   // TODO: Implementar limitação de taxa
 17 |   return checkDatabase(credentials);
----

Exemplos de Quando Usado​

  • Quando solicitado a refatorar uma função, o AI Cockpit Reasoning primeiro pesquisa todos os locais onde a função é usada para garantir alterações abrangentes.
  • Ao investigar bugs, o AI Cockpit Reasoning procura por padrões semelhantes para identificar problemas relacionados em toda a base de código.
  • Ao lidar com a dívida técnica, o AI Cockpit Reasoning localiza todos os comentários TODO em todo o projeto.
  • Ao analisar dependências, o AI Cockpit Reasoning encontra todas as importações de um módulo específico.

Exemplos de Uso​

Procurando por comentários TODO em todos os arquivos JavaScript:

<search_files>
<path>src</path>
<regex>TODO|FIXME</regex>
<file_pattern>*.js</file_pattern>
</search_files>

Encontrando todos os usos de uma função específica:

<search_files>
<path>.</path>
<regex>function\s+calculateTotal</regex>
<file_pattern>*.{js,ts}</file_pattern>
</search_files>

Procurando por um padrão de importação específico em todo o projeto:

<search_files>
<path>.</path>
<regex>import\s+.*\s+from\s+['"]@components/</regex>
</search_files>