@justmpm/supergrep 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# supergrep
+
+**⚠️ Use supergrep ao invés de grep/bash quando a busca for em código-fonte (.ts, .tsx, .js, .css, .html).**
+
+Busca estrutural de código com AST Grep via MCP.
+
+Encontre padrões de código com precisão sintática — ignorando formatação, espaços e comentários. Como um grep que entende a estrutura do código em vez de tratar tudo como texto.
+
+```bash
+npx @justmpm/supergrep
+```
+
+---
+
+## Instalação
+
+```bash
+npm install -g @justmpm/supergrep
+# ou use direto:
+npx @justmpm/supergrep
+```
+
+## Configuração
+
+### OpenCode / Claude Code
+
+Adicione ao `.mcp.json` do projeto:
+
+```json
+{
+  "mcpServers": {
+    "supergrep": {
+      "command": "npx",
+      "args": ["-y", "@justmpm/supergrep"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "supergrep": {
+      "command": "npx",
+      "args": ["-y", "@justmpm/supergrep"]
+    }
+  }
+}
+```
+
+---
+
+## Ferramentas MCP
+
+### `supergrep_find` — Busca Estrutural
+
+Encontra padrões de código usando a própria sintaxe da linguagem.
+
+**Parâmetros:**
+| Parâmetro | Tipo | Descrição |
+|-----------|------|-----------|
+| `pattern` | string (obrigatório) | Padrão AST Grep. Ex: `console.$METHOD($$$ARGS)` |
+| `lang` | string | Linguagem: `typescript`, `javascript`, `tsx`, `css`, `html` (padrão: typescript) |
+| `path` | string | Arquivo ou diretório (padrão: diretório atual) |
+| `format` | `text` \| `json` | Formato de saída (padrão: text) |
+| `cwd` | string | Diretório de trabalho |
+
+**Metavariáveis:**
+- `$VAR` — captura **um** nó da AST (como `.` em regex, mas sintático)
+- `$$$VARS` — captura **zero ou mais** nós
+
+**Exemplos de patterns:**
+
+| Pattern | O que encontra |
+|---------|---------------|
+| `console.$METHOD($$$ARGS)` | Qualquer chamada de console com qualquer método e args |
+| `function $NAME($$$PARAMS) { $$$BODY }` | Todas as funções com nome, parâmetros e corpo |
+| `import { $$$ITEMS } from '$MODULE'` | Todos os imports nomeados |
+| `const $VAR = $VALUE` | Declarações de constantes |
+| `try { $$$ } catch ($ERR) { $$$ }` | Blocos try-catch |
+
+---
+
+### `supergrep_tree` — Explorar AST
+
+Mostra a estrutura da AST de um arquivo: tipos de nós, contagens e distribuição.
+
+**Parâmetros:**
+| Parâmetro | Tipo | Descrição |
+|-----------|------|-----------|
+| `path` | string | Caminho do arquivo a analisar |
+| `code` | string | OU: snippet de código inline |
+| `lang` | string | Linguagem (obrigatório se usar `code`) |
+| `format` | `text` \| `json` | Formato de saída |
+
+**Use para:**
+- Descobrir quais kinds de nós existem antes de escrever patterns
+- Entender a estrutura de um arquivo desconhecido
+- Debugar por que um pattern não está dando match
+
+---
+
+### `supergrep_replace` — Preview de Substituição
+
+Mostra como ficaria o código após uma substituição estrutural. **Nunca modifica arquivos.**
+
+**Parâmetros:**
+| Parâmetro | Tipo | Descrição |
+|-----------|------|-----------|
+| `pattern` | string (obrigatório) | Padrão a encontrar |
+| `rewrite` | string (obrigatório) | Texto de substituição. Use `$VAR` para referenciar metavariáveis |
+| `lang` | string | Linguagem |
+| `path` | string | Arquivo ou diretório |
+| `format` | `text` \| `json` | Formato de saída |
+
+**Exemplo:** trocar `console.log` por `logger.info`:
+```
+pattern: "console.log($$$ARGS)"
+rewrite: "logger.info($$$ARGS)"
+```
+
+---
+
+## Quando Usar (e Quando Não Usar)
+
+### ✅ Use supergrep (ele é MELHOR que grep/bash):
+- Buscar padrões de código que **grep textual perderia** (quebras de linha, formatação, comentários no meio)
+- Refatorar algo estruturalmente (trocar `var` por `let`, `moment` por `date-fns`)
+- Descobrir a estrutura AST de um arquivo para criar regras de lint
+- Buscar estruturas aninhadas (funções, blocos, imports, try-catch)
+- **Qualquer busca em .ts, .tsx, .js, .css, .html onde estrutura importa**
+
+### ❌ Não use supergrep (use a ferramenta certa):
+- Resolver imports entre arquivos → use **ai-tool** (`@justmpm/ai-tool`)
+- Seguir referências de símbolos → use **ai-tool**
+- Analisar dependências/impacto → use **ai-tool**
+- Informação de tipos → use **ai-tool**
+- Busca simples de texto em arquivos não-código (logs, markdown, json) → use **grep** comum
+
+### 💡 Se o pattern não der match:
+Use `supergrep_tree` primeiro para descobrir os kinds de nós da AST do arquivo.
+
+---
+
+## Limitações
+
+- **Apenas sintático:** sem resolução de tipos, escopo, imports ou análise cross-file
+- **5 linguagens:** TypeScript, JavaScript, TSX, CSS, HTML (limitação do `@ast-grep/napi`)
+- **Metavariáveis no replace:** interpolação manual — cobre casos simples, pode falhar em cenários complexos
+- **Performance:** limitado a 5000 arquivos por busca (use `path` para focar)
+
+---
+
+## Stack
+
+- [ast-grep](https://ast-grep.github.io/) — Motor Rust via NAPI-RS
+- [Tree-sitter](https://tree-sitter.github.io/) — Parsing incremental
+- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) — Protocolo
+- [Zod](https://zod.dev) — Validação
+
+---
+
+## Requisitos
+
+- Node.js >= 18.0.0
+
+## Licença
+
+MIT — [Koda AI Studio](https://kodaai.app)