@justmpm/supergrep 0.1.0 → 0.1.1

package/README.md

@@ -16,7 +16,7 @@ npx @justmpm/supergrep
 
 ```bash
 npm install -g @justmpm/supergrep
-# ou use direto:
+# ou use direto sem instalar:
 npx @justmpm/supergrep
 ```
 
@@ -24,6 +24,8 @@ npx @justmpm/supergrep
 
 ### OpenCode / Claude Code
 
+#### Via npx (sem instalação)
+
 Adicione ao `.mcp.json` do projeto:
 
 ```json
@@ -37,11 +39,29 @@ Adicione ao `.mcp.json` do projeto:
 }
 ```
 
+#### Com instalação local
+
+```bash
+npm install -g @justmpm/supergrep
+```
+
+```json
+{
+  "mcpServers": {
+    "supergrep": {
+      "command": "supergrep"
+    }
+  }
+}
+```
+
 ### Claude Desktop
 
 **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
+#### Via npx (sem instalação)
+
 ```json
 {
   "mcpServers": {
@@ -53,6 +73,22 @@ Adicione ao `.mcp.json` do projeto:
 }
 ```
 
+#### Com instalação local
+
+```bash
+npm install -g @justmpm/supergrep
+```
+
+```json
+{
+  "mcpServers": {
+    "supergrep": {
+      "command": "supergrep"
+    }
+  }
+}
+```
+
 ---
 
 ## Ferramentas MCP

package/dist/{chunk-4MPFPILM.js → chunk-SENMQNTX.js}

@@ -96,7 +96,8 @@ var IGNORED_DIRS = [
 ];
 
 // src/tools/find.ts
-var META_VAR_RE = /\$(\$\$)?([A-Z_][A-Z0-9_]*)/g;
+var MULTI_META_RE = /\$\$\$([A-Z_][A-Z0-9_]*)/g;
+var SINGLE_META_RE = /(?<!\$)\$(?:\$\$)?([A-Z_][A-Z0-9_]*)/g;
 async function findPattern(options) {
   const startTime = Date.now();
   const warnings = [];
@@ -109,7 +110,7 @@ async function findPattern(options) {
   const searchDir = resolve(cwd, options.path ?? ".");
   const files = await findCodeFiles(searchDir, cwd, lang);
   warnings.push(...files.warnings);
-  const metaVarNames = extractMetaVarNames(options.pattern);
+  const metaVars = extractMetaVarInfo(options.pattern);
   const matches = [];
   for (const filePath of files.paths) {
     try {
@@ -129,10 +130,17 @@ async function findPattern(options) {
           metaVariables: {},
           context: extractContextLines(source, range.start.line, 2)
         };
-        for (const varName of metaVarNames) {
-          const metaNode = node.getMatch(varName);
-          if (metaNode) {
-            match.metaVariables[varName] = metaNode.text();
+        for (const { name, isMulti } of metaVars) {
+          if (isMulti) {
+            const multiNodes = node.getMultipleMatches(name);
+            if (multiNodes.length > 0) {
+              match.metaVariables[name] = multiNodes.map((n) => n.text()).join(", ");
+            }
+          } else {
+            const metaNode = node.getMatch(name);
+            if (metaNode) {
+              match.metaVariables[name] = metaNode.text();
+            }
           }
         }
         matches.push(match);
@@ -155,14 +163,27 @@ async function findPattern(options) {
     warnings
   };
 }
-function extractMetaVarNames(pattern) {
-  const names = /* @__PURE__ */ new Set();
+function extractMetaVarInfo(pattern) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
   let match;
-  const re = new RegExp(META_VAR_RE.source, "g");
-  while ((match = re.exec(pattern)) !== null) {
-    names.add(match[2]);
+  const multiRe = new RegExp(MULTI_META_RE.source, "g");
+  while ((match = multiRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: true });
+    }
+  }
+  const singleRe = new RegExp(SINGLE_META_RE.source, "g");
+  while ((match = singleRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: false });
+    }
   }
-  return [...names];
+  return result;
 }
 function extractContextLines(source, line, contextLines) {
   const lines = source.split("\n");
@@ -186,7 +207,6 @@ function resolveLangForOptions(options, _cwd, warnings) {
       if (detected) return detected;
     }
   }
-  warnings.push("Linguagem nao especificada, usando TypeScript como default.");
   return resolveLang("typescript");
 }
 function validatePattern(pattern, lang) {
@@ -287,11 +307,9 @@ async function exploreTree(options) {
     if (options.lang) {
       detectedLang = resolveLang(options.lang);
       if (!detectedLang) {
-        warnings.push(`Linguagem "${options.lang}" nao reconhecida, usando TypeScript.`);
         detectedLang = resolveLang("typescript");
       }
     } else {
-      warnings.push("Linguagem nao especificada para codigo inline, usando TypeScript.");
       detectedLang = resolveLang("typescript");
     }
   } else if (options.path) {
@@ -378,7 +396,8 @@ var TreeParseError = class extends Error {
 import { parse as parse3 } from "@ast-grep/napi";
 import { readFile as readFile3, readdir as readdir2, stat as stat2 } from "fs/promises";
 import { join as join2, resolve as resolve3, relative as relative3 } from "path";
-var META_VAR_RE2 = /\$(\$\$)?([A-Z_][A-Z0-9_]*)/g;
+var MULTI_META_RE2 = /\$\$\$([A-Z_][A-Z0-9_]*)/g;
+var SINGLE_META_RE2 = /(?<!\$)\$(?:\$\$)?([A-Z_][A-Z0-9_]*)/g;
 async function replacePreview(options) {
   const warnings = [];
   const cwd = options.cwd ?? process.cwd();
@@ -397,13 +416,12 @@ async function replacePreview(options) {
     lang = detected;
     warnings.push(`Linguagem detectada automaticamente: ${langName(lang)}`);
   } else {
-    warnings.push("Linguagem nao especificada, usando TypeScript como default.");
     lang = resolveLang("typescript");
   }
   validateReplacePattern(options.pattern, lang);
   const searchDir = resolve3(cwd, options.path ?? ".");
   const files = await findCodeFiles2(searchDir);
-  const metaVarNames = extractMetaVarNames2(options.pattern);
+  const metaVars = extractMetaVarInfo2(options.pattern);
   const changes = [];
   for (const filePath of files.paths) {
     try {
@@ -412,15 +430,22 @@ async function replacePreview(options) {
       const root = ast.root();
       const foundNodes = root.findAll(options.pattern);
       for (const node of foundNodes) {
-        const metaVars = {};
-        for (const varName of metaVarNames) {
-          const metaNode = node.getMatch(varName);
-          if (metaNode) {
-            metaVars[varName] = metaNode.text();
+        const metaVarValues = {};
+        for (const { name, isMulti } of metaVars) {
+          if (isMulti) {
+            const multiNodes = node.getMultipleMatches(name);
+            if (multiNodes.length > 0) {
+              metaVarValues[name] = multiNodes.map((n) => n.text()).join(", ");
+            }
+          } else {
+            const metaNode = node.getMatch(name);
+            if (metaNode) {
+              metaVarValues[name] = metaNode.text();
+            }
           }
         }
         let interpolated = options.rewrite;
-        for (const [name, value] of Object.entries(metaVars)) {
+        for (const [name, value] of Object.entries(metaVarValues)) {
           interpolated = interpolated.replaceAll(
             new RegExp(`\\$${name}\\b`, "g"),
             value
@@ -452,14 +477,27 @@ async function replacePreview(options) {
     warnings
   };
 }
-function extractMetaVarNames2(pattern) {
-  const names = /* @__PURE__ */ new Set();
+function extractMetaVarInfo2(pattern) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
   let match;
-  const re = new RegExp(META_VAR_RE2.source, "g");
-  while ((match = re.exec(pattern)) !== null) {
-    names.add(match[2]);
+  const multiRe = new RegExp(MULTI_META_RE2.source, "g");
+  while ((match = multiRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: true });
+    }
+  }
+  const singleRe = new RegExp(SINGLE_META_RE2.source, "g");
+  while ((match = singleRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: false });
+    }
   }
-  return [...names];
+  return result;
 }
 function validateReplacePattern(pattern, lang) {
   try {
@@ -566,17 +604,18 @@ function hint(command, ctx, params) {
 }
 var NEXT_STEPS = {
   find: [
-    { command: "tree", description: "explorar a estrutura AST de um arquivo com matches" },
-    { command: "find", description: "refinar a busca com outro padrao" },
-    { command: "replace", description: "pre-visualizar uma substituicao estrutural" }
+    { command: "tree", description: "explorar a AST do arquivo com matches para entender a estrutura" },
+    { command: "find", description: "refinar a busca com um pattern mais especifico" },
+    { command: "replace", description: "pre-visualizar como ficaria uma substituicao nos matches" }
   ],
   tree: [
-    { command: "find", description: "usar os kinds descobertos para buscar padroes" },
-    { command: "tree", description: "explorar outro arquivo" }
+    { command: "find", description: "usar os kinds descobertos para criar um pattern de busca (ex: $FUNC($$$ARGS) para call_expression)" },
+    { command: "tree", description: "explorar outro arquivo ou snippet" }
   ],
   replace: [
-    { command: "find", description: "ver todos os matches do padrao antes de substituir" },
-    { command: "tree", description: "explorar a estrutura AST para criar padroes melhores" }
+    { command: "find", description: "ver todos os matches do pattern antes de substituir" },
+    { command: "replace", description: "testar outra string de rewrite no preview" },
+    { command: "tree", description: "explorar a AST para criar patterns mais precisos" }
   ]
 };
 function nextSteps(command, ctx) {
@@ -611,9 +650,10 @@ function recoveryHint(errorType, ctx, _extra) {
     case "lang_not_supported":
       return `
 \u{1F4A1} Linguagem nao suportada. Dicas:
-   \u2192 ${hint("tree", ctx)} - use com arquivos de codigo fonte (.ts, .py, .rs, etc.)
-   \u2192 Extensoes suportadas: .ts, .tsx, .js, .py, .rs, .go, .java, .kt, .swift e mais
-   \u2192 Para JSON, YAML, CSS e HTML, use a linguagem correspondente
+   \u2192 O @ast-grep/napi suporta apenas 5 linguagens: TypeScript, JavaScript, TSX, CSS, HTML
+   \u2192 Para Python, Rust, Go e outras, use o CLI: npx @ast-grep/cli
+   \u2192 ${hint("tree", ctx)} - explore a AST de um arquivo existente
+   \u2192 ${hint("find_lang", ctx)} - especifique a linguagem manualmente
 `;
     case "lang_not_detected":
       return `
@@ -997,7 +1037,9 @@ function registerAllTools(server2) {
     "supergrep_find",
     {
       title: "Structural Code Search",
-      description: `\u26A0\uFE0F PREFIRA esta ferramenta ao inves de grep/bash quando a busca for em CODIGO-FONTE.
+      description: `\u26A0\uFE0F Use esta ferramenta em vez de grep/bash quando a busca for em CODIGO-FONTE
+ESTRUTURADO (TS/JS/TSX/CSS/HTML). Para texto plano, logs, markdown ou JSON,
+prefira grep comum.
 
 Busca estrutural de codigo usando AST Grep. Diferente do grep textual (que
 quebra com quebras de linha, espacos extras ou comentarios no meio), o
@@ -1005,12 +1047,12 @@ supergrep entende a SINTAXE da linguagem \u2014 ele busca pela ESTRUTURA do codi
 nao pelo texto cru.
 
 Escreva o padrao de busca na propria linguagem de programacao, usando
-metavariaveis ($VAR, $$$VARS) como curingas que capturam partes dinamicas.
+metavariaveis ($VAR, $$VAR, $$$VARS) como curingas que capturam partes dinamicas.
 
 \u{1F4E6} LINGUAGENS SUPORTADAS (apenas 5):
-  \u2022 typescript  (.ts)
+  \u2022 typescript  (.ts)        \u2014 apenas .ts puro (sem JSX)
   \u2022 javascript  (.js, .jsx, .mjs, .cjs)
-  \u2022 tsx         (.tsx)
+  \u2022 tsx         (.tsx)       \u2014 .tsx COM JSX/React (requer lang: 'tsx')
   \u2022 css         (.css, .scss, .less)
   \u2022 html        (.html, .htm)
 
@@ -1024,7 +1066,7 @@ Cada arquivo e analisado isoladamente. Para analise semantica, use ai-tool.
   \u2022 "Localize imports de uma lib deprecated"
   \u2022 "Busque componentes React que usam useEffect sem dependencias"
   \u2022 "Ache arrow functions que recebem exatamente 1 parametro"
-  \u2022 QUALQUER busca estrutural onde grep/quebraria com formatacao
+  \u2022 QUALQUER busca estrutural onde grep quebraria com formatacao
 
 \u274C QUANDO NAO USAR (prefira ai-tool):
   \u2022 "Onde a funcao useAuth e definida e usada?" \u2192 resolucao de escopo (aitool_find)
@@ -1032,17 +1074,31 @@ Cada arquivo e analisado isoladamente. Para analise semantica, use ai-tool.
   \u2022 "Qual o tipo real desta variavel?" \u2192 type checker (aitool_file_context)
   \u2022 Busca em texto plano, logs, markdown \u2192 use grep/bash comum
 
+\u26A0\uFE0F O QUE O GREP NAO RESOLVE (anti-exemplos):
+  \u2022 grep falha com quebra de linha:
+    \u274C GREP: console\\n  .log("oi")     \u2192 nao encontra
+    \u2705 SUPERGREP: console.log("oi")     \u2192 encontra (ignora formatacao)
+  \u2022 grep falha com espacos extras:
+    \u274C GREP: const   x =   1           \u2192 precisa de regex complexa
+    \u2705 SUPERGREP: const x = 1          \u2192 resolve pela estrutura
+
 \u{1F4DD} EXEMPLOS DE PATTERNS:
-  \u2022 console.$METHOD($$$ARGS)         \u2192 captura metodo e argumentos
-  \u2022 function $NAME($$$PARAMS) { $$$BODY }  \u2192 captura funcoes
+  \u2022 console.$METHOD($MSG)              \u2192 captura metodo e 1 argumento
+  \u2022 console.$METHOD($$$ARGS)           \u2192 captura metodo e todos os argumentos
+  \u2022 function $NAME($$$PARAMS) { $$$BODY }  \u2192 captura funcoes completas
   \u2022 import { $$$ITEMS } from '$MODULE'     \u2192 captura imports
-  \u2022 const $VAR = $VALUE              \u2192 captura declaracoes
-  \u2022 try { $$$ } catch ($ERR) { $$$ } \u2192 captura try-catch
-  \u2022 await $FUNC($$$ARGS)             \u2192 captura chamadas assincronas
+  \u2022 const $VAR = $VALUE                \u2192 captura declaracoes
+  \u2022 try { $$$ } catch ($ERR) { $$$ }   \u2192 captura try-catch
+  \u2022 await $FUNC($$$ARGS)               \u2192 captura chamadas assincronas
 
 \u{1F524} METAVARIAVEIS:
-  \u2022 $VAR    \u2192 captura UM no da AST (ex: um identificador, uma string)
-  \u2022 $$$VARS \u2192 captura ZERO OU MAIS nos (ex: todos os argumentos, corpo)
+  \u2022 $VAR    \u2192 captura UM no nomeado (ex: um identificador, uma string, um numero)
+  \u2022 $$VAR   \u2192 captura UM no (incluindo nos nao-nomeados como operadores +, -)
+  \u2022 $$$VARS \u2192 captura ZERO OU MAIS nos (ex: todos os args, corpo da funcao)
+
+  \u26A0\uFE0F $$$VARS captura multiplos nos \u2014 o texto de cada no e concatenado com
+  ", " no resultado da metavariable. Para multi-nos complexos (onde a
+  concatenacao simples nao basta), use supergrep_tree para inspecionar a AST.
 
 \u{1F4A1} DICA: Se o pattern nao der match, use supergrep_tree primeiro para
 descobrir os kinds de nos disponiveis e ajustar o pattern.
@@ -1095,21 +1151,34 @@ ${warnings.map((w) => `   \u2022 ${w}`).join("\n")}` : "";
     "supergrep_tree",
     {
       title: "Explore AST Structure",
-      description: `Explora a estrutura da AST (Abstract Syntax Tree) de um arquivo.
+      description: `Explora a estrutura da AST (Abstract Syntax Tree) de um arquivo ou snippet.
 
 Mostra todos os tipos de nos (kinds) presentes, com contagens e distribuicao.
 Util para entender a estrutura do codigo e descobrir quais kinds usar
-em patterns de busca ou regras YAML.
+em patterns de busca.
+
+\u{1F4D6} O QUE E UM "KIND":
+Um kind e o tipo de um no na arvore sintatica. Exemplos:
+  \u2022 function_declaration \u2014 declaracao de funcao
+  \u2022 call_expression      \u2014 chamada de funcao/metodo
+  \u2022 identifier           \u2014 nome de variavel, funcao, etc.
+  \u2022 string_fragment      \u2014 literal de string
+Cada estrutura de codigo vira um kind diferente na AST.
+
+\u{1F4A1} Como usar os kinds: ao ver call_expression no tree, voce pode buscar
+chamadas de funcao com o pattern: $FUNC($$$ARGS)
 
 QUANDO USAR:
-- "Quais tipos de nos existem neste arquivo TypeScript?"
-- "Como escrever um pattern para capturar certas estruturas?"
-- "Preciso descobrir os kinds para uma regra de lint customizada"
-- Antes de escrever um pattern complexo, para conhecer a AST
+  - "Quais tipos de nos existem neste arquivo TypeScript?"
+  - "Como escrever um pattern para capturar certas estruturas?"
+  - "Preciso descobrir os kinds para uma regra de lint customizada"
+  - Antes de escrever um pattern complexo, para conhecer a AST
+  - Testar um snippet de codigo sem criar arquivo (use o parametro code)
 
 QUANDO NAO USAR:
-- Para buscar padroes no codigo \u2192 use supergrep_find
-- Para ver o conteudo do arquivo \u2192 leia o arquivo diretamente
+  - Para buscar padroes no codigo \u2192 use supergrep_find
+  - Para ver o conteudo do arquivo \u2192 leia o arquivo diretamente
+  - Para diretorios (analisar multiplos arquivos) \u2192 use supergrep_find com o pattern desejado. supergrep_tree analisa UM arquivo ou snippet por vez.
 
 Workflow: supergrep_tree \u2192 supergrep_find (usar kinds descobertos)`,
       inputSchema: {
@@ -1158,27 +1227,35 @@ ${warnings.map((w) => `   \u2022 ${w}`).join("\n")}` : "";
   server2.registerTool(
     "supergrep_replace",
     {
-      title: "Preview Structural Replacement",
-      description: `Pre-visualiza uma substituicao estrutural de codigo (NAO modifica arquivos).
+      title: "Preview Structural Replacement (read-only)",
+      description: `\u{1F504} PREVIEW de substituicao estrutural de codigo (NAO modifica arquivos).
 
 Encontra padroes com AST Grep e mostra um diff de como o codigo ficaria
 apos a substituicao. Util para planejar refatoracoes em larga escala.
 
-LIMITACAO: Metavariaveis ($VAR) no rewrite sao interpoladas manualmente.
-Para casos complexos, verifique o preview antes de aplicar.
+\u26A0\uFE0F LIMITACAO DE METAVARIAVEIS NO REWRITE:
+  \u2022 $VAR (single) \u2192 interpola corretamente \u2705
+    Ex: console.$METHOD($MSG) \u2192 logger.$METHOD($MSG)
+  \u2022 $$$VARS (multi) \u2192 interpolado como texto concatenado dos nos \u26A0\uFE0F
+    Ex: console.log($$$ARGS) \u2192 logger.info(texto, dos, args)
+    Para casos complexos, verifique o preview antes de aplicar.
+
+  A API napi do AST Grep nao interpola metavariaveis automaticamente.
+  O supergrep faz interpolacao manual: textos dos nos sao concatenados
+  com ", " e injetados no lugar do $VAR no rewrite.
 
 QUANDO USAR:
-- "Como ficaria se eu trocasse console.log por logger.info?"
-- "Preview de substituir var por let em todo o projeto"
-- "Mostre o diff de trocar moment() por date-fns"
-- Planejar refatoracoes estruturais antes de aplicar
+  - "Como ficaria se eu trocasse console.log por logger.info?"
+  - "Preview de substituir var por let em todo o projeto"
+  - "Mostre o diff de trocar moment() por date-fns"
+  - Planejar refatoracoes estruturais antes de aplicar
 
 QUANDO NAO USAR:
-- Para buscar padroes (sem substituir) \u2192 use supergrep_find
-- Para aplicar a substituicao de fato \u2192 use uma ferramenta de edicao
-- Para refatoracoes que envolvem logica complexa \u2192 implemente manualmente
+  - Para buscar padroes (sem substituir) \u2192 use supergrep_find
+  - Para aplicar a substituicao de fato \u2192 use edit (substituicao exata) ou write (arquivo completo). O preview do supergrep_replace serve como guia.
+  - Para refatoracoes que envolvem logica complexa \u2192 implemente manualmente
 
-Workflow: supergrep_find \u2192 supergrep_replace (preview) \u2192 aplicar mudancas`,
+Workflow: supergrep_find \u2192 supergrep_replace (preview) \u2192 aplicar mudancas com edit/write`,
       inputSchema: {
         pattern: z.string().min(1).describe(
           "Padrao AST Grep a encontrar. Ex: 'console.log($$$ARGS)'"

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   startMcpServer
-} from "./chunk-4MPFPILM.js";
+} from "./chunk-SENMQNTX.js";
 
 // src/cli.ts
 startMcpServer().catch((err) => {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   startMcpServer
-} from "./chunk-4MPFPILM.js";
+} from "./chunk-SENMQNTX.js";
 
 // src/index.ts
 var VERSION = "0.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justmpm/supergrep",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server para busca estrutural de código com AST Grep. Encontra padrões de código com precisão sintática, ignorando formatação e comentários. Suporta 20+ linguagens via Tree-sitter.",
   "keywords": [
     "ast-grep",