feat: comentários de documentação no hover e engine 1.4.0

.github/workflows/codeql.yml

@@ -7,6 +7,7 @@ on:
     branches: [master]
   schedule:
     - cron: '40 23 * * 1'
+  workflow_dispatch:
 
 permissions: {}
 
@@ -23,12 +24,12 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
+        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
         with:
           languages: javascript-typescript
           build-mode: none
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
+        uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
         with:
           category: '/language:javascript-typescript'

.github/workflows/publish.yml

@@ -126,7 +126,7 @@ jobs:
         run: echo "file=$(ls *.vsix | head -1)" >> "$GITHUB_OUTPUT"
 
       - name: Upload VSIX to GitHub Release
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           files: ${{ steps.vsix.outputs.file }}
 

.github/workflows/scorecard.yml

@@ -36,6 +36,6 @@ jobs:
           publish_results: true
 
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
         with:
           sarif_file: results.sarif

CLAUDE.md

@@ -142,7 +142,7 @@ O que vai no VSIX: `out/editor/extension.js`, `engines/`, `syntaxes/`, `template
 
 ## Diagnósticos conhecidos do motor
 
-Ver [docs/features.md](docs/features.md) para a tabela completa de códigos PP0001–PP0013.
+Ver [docs/features.md](docs/features.md) para a tabela completa de códigos PP0001–PP0019.
 
 ---
 

README.md

@@ -10,53 +10,152 @@
   [![CodeQL](https://img.shields.io/github/actions/workflow/status/NullSablex/PawnPro/codeql.yml?style=flat-square&logo=github&label=CodeQL)](https://github.com/NullSablex/PawnPro/actions/workflows/codeql.yml)
   [![Security](https://img.shields.io/github/actions/workflow/status/NullSablex/PawnPro/security.yml?style=flat-square&logo=github&label=Security)](https://github.com/NullSablex/PawnPro/actions/workflows/security.yml)
   [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/NullSablex/PawnPro/badge?style=flat-square)](https://scorecard.dev/viewer/?uri=github.com/NullSablex/PawnPro)
+  [![Downloads](https://img.shields.io/github/downloads/NullSablex/PawnPro/total?style=flat-square&logo=github&label=downloads)](https://github.com/NullSablex/PawnPro/releases)
+  [![Stars](https://img.shields.io/github/stars/NullSablex/PawnPro?style=flat-square&logo=github&label=stars)](https://github.com/NullSablex/PawnPro/stargazers)
   [![License](https://img.shields.io/badge/licença-Source--Available-blue?style=flat-square)](LICENSE.md)
 
   ![Windows x64](https://img.shields.io/badge/Windows-x64-0078D4?style=flat-square&logo=windows11&logoColor=white)
   ![Linux x64](https://img.shields.io/badge/Linux-x64%20·%20arm64-FCC624?style=flat-square&logo=linux&logoColor=black)
   ![macOS x64](https://img.shields.io/badge/macOS-x64%20·%20arm64-000000?style=flat-square&logo=apple&logoColor=white)
 </div>
 
-Extensão para desenvolvimento em **Pawn** (SA-MP e open.mp) no Visual Studio Code e VSCodium: IntelliSense e diagnósticos por um motor LSP em Rust, com ferramentas integradas para edição, compilação, depuração e gerenciamento de servidor.
-
-## Recursos
-
-- **IntelliSense** — auto-complete, hover, signature help, CodeLens (referências) e coloração semântica para Pawn, cobrindo os includes transitivos.
-- **Diagnósticos** — 18 códigos `PP####` para includes não encontrados, erros estruturais, código morto, depreciação, nomenclatura e mais (ver [docs/features.md](docs/features.md)).
-- **Compilação** — `Ctrl+Alt+B` compila o `.pwn` ativo; detecção automática do `pawncc` via `$PAWNCC`, `$PATH` e subdiretórios do workspace.
-- **Depuração** — sessão de depuração via DAP (`F5`): breakpoints (simples, condicionais, por contagem, logpoints), passo a passo, inspeção de variáveis e watch. Usa um plugin de servidor (SA-MP / open.mp); ver [docs/debugging.md](docs/debugging.md).
-- **Formatação** — formatação de documento e de seleção (`Ctrl+K Ctrl+F`), com estilos configuráveis (Allman, K&R, compacto ou personalizado).
-- **Assistente de nomenclatura** — avisos opcionais sobre nomes pobres e convenções de caixa por categoria de identificador.
-- **Servidor SA-MP / open.mp** — Start, Stop, Restart e envio de comandos RCON pelo terminal integrado; painel lateral com histórico e favoritos.
-- **Templates** — Gamemode e Filterscript (open.mp e SA-MP) e Include (open.mp), filtrados pela plataforma configurada.
-- **Biblioteca de recursos** — vitrine de plugins, filterscripts e includes (prévia).
-- **Painel de configurações** — interface gráfica (`PawnPro: Configurações`) com todas as opções editáveis sem tocar em JSON.
-- **Temas de sintaxe** — esquemas claro/escuro (clássico e moderno) com reaplicação automática ao trocar o tema do editor.
-- **Multi-idioma** — interface e diagnósticos em português, inglês, espanhol, romeno e russo, configuráveis de forma independente.
-- **Realce de sintaxe adicional** — `.toml`/`package.lock` e prévia de cor (`swatch`) em literais `0xRRGGBBAA`.
-- **Motor Rust LSP** — análise nativa via [pawnpro-engine](https://github.com/NullSablex/PawnPro-Engine); iniciado automaticamente se o binário estiver presente em `engines/`.
-- **Arquivos Pawn** — `.pwn`, `.inc`, `.p` e `.pawn` recebem IntelliSense e diagnósticos.
+**Uma IDE completa para Pawn dentro do seu editor.** O PawnPro é uma extensão para
+VS Code e VSCodium que traz para o desenvolvimento SA-MP / open.mp o que outras
+linguagens têm há anos: um motor de análise que entende o seu código de verdade,
+compilação e depuração com um atalho, e o servidor sob controle sem sair do editor.
+
+> Escrever gamemode não precisa ser editor de texto, terminal e ALT+TAB.
+
+## Por que existe
+
+Quem desenvolve em Pawn conhece o ciclo: salvar, trocar de janela, compilar,
+ler um erro sem contexto, voltar, procurar a linha. Erro de digitação num nome de
+função? Só se descobre no compilador. Quer saber o que aquele native faz? Abre o
+`.inc` e lê o código.
+
+O PawnPro corta esse ciclo. O código é analisado enquanto você escreve — por um
+**motor próprio escrito em Rust**, não por expressões regulares — então o erro
+aparece na linha onde está, o autocomplete conhece os seus includes, e a
+documentação da função aparece ao passar o mouse.
+
+## O que você ganha
+
+### Enquanto escreve
+
+- **Autocomplete que conhece o seu projeto** — funções, natives, constantes e
+  macros de todos os `.inc` que você inclui, transitivamente. Ordenado por
+  proximidade: o que está perto do cursor vem primeiro.
+- **Documentação no hover e no signature help** — o comentário acima da função
+  vira texto formatado, nos formatos **Javadoc** (`@param`) e **XMLdoc**
+  (`<summary>`, o que o `omp-stdlib` do open.mp usa). Ao digitar a chamada, a
+  descrição do parâmetro em que você está aparece sozinha.
+- **19 diagnósticos** com código próprio (`PP####`) — include que não existe,
+  chave sem fechar, código inalcançável, função depreciada, variável não usada.
+  **13 deles têm correção automática** (`Ctrl+.`).
+- **Ir para a definição, referências e renomear** em todo o projeto.
+- **Prévia de cor** nos literais `0xRRGGBBAA` e `{RRGGBB}`, com seletor de cores.
+
+### Na hora de compilar e testar
+
+- **`Ctrl+Alt+B` compila** — o `pawncc` é encontrado sozinho (via `$PAWNCC`,
+  `PATH` ou dentro do projeto). Os erros voltam clicáveis no painel de problemas.
+- **`F5` depura de verdade** — breakpoints (simples, condicionais, por contagem e
+  logpoints), passo a passo, inspeção de variáveis, watch, call stack e
+  data breakpoints. Depuração real de gamemode, não `print()` espalhado.
+- **Servidor no painel lateral** — iniciar, parar, reiniciar e enviar comandos
+  RCON sem abrir terminal. Histórico e favoritos com busca, e o log acompanhado
+  em tempo real.
+
+### Para o projeto não virar bagunça
+
+- **Formatação** com estilos configuráveis (Allman, K&R, compacto ou seu próprio).
+- **Assistente de nomenclatura** — convenções de caixa por categoria de
+  identificador, e um **padrão próprio por expressão regular** quando os estilos
+  prontos não descrevem a convenção da casa (`g_` nas globais, por exemplo).
+- **Templates** de gamemode, filterscript e include, já no formato certo da
+  plataforma que você usa.
+
+### E porque ninguém programa igual
+
+- **Cinco idiomas** — português, inglês, espanhol, romeno e russo. A interface e
+  os diagnósticos são configuráveis **de forma independente**: dá para ter o
+  editor em português e os erros em inglês.
+- **Painel de configurações visual** — todas as opções sem tocar em JSON.
+- **Temas de sintaxe** claro e escuro, que acompanham o tema do editor.
+- **Cor de destaque** — seis cores para a interface da extensão, ou o padrão que
+  herda do seu tema.
+
+## Instalação
+
+Procure por **PawnPro** no marketplace do seu editor, ou:
+
+```
+ext install NullSablex.pawnpro
+```
+
+Também disponível no [Open VSX](https://open-vsx.org/extension/NullSablex/pawnpro)
+para VSCodium e editores derivados.
+
+**Funciona em Windows, Linux e macOS** (x64 e arm64). O motor de análise é um
+binário nativo que acompanha a extensão — não precisa instalar Rust, Node nem
+nada além do editor.
+
+## Primeiros passos
+
+1. Abra a **pasta** do seu gamemode (não o arquivo solto — a extensão precisa da
+   pasta para achar os includes).
+2. Abra um `.pwn`. O motor inicia sozinho e começa a analisar.
+3. `Ctrl+Alt+B` para compilar, `F5` para depurar.
+
+Se os includes não forem encontrados, abra **PawnPro: Configurações** pela barra
+de status e aponte o caminho do `pawno/include` — ou deixe a detecção automática
+procurar nos lugares usuais.
 
 ## Configuração
 
-As configurações são gerenciadas por arquivos JSON independentes do editor:
+Independente do editor, em JSON simples:
 
 | Arquivo | Escopo |
 |---------|--------|
 | `~/.pawnpro/config.json` | Global (todos os projetos) |
-| `.pawnpro/config.json` | Projeto (sobrescreve global) |
-| `.pawnpro/state.json` | Estado local (favoritos, histórico do servidor) |
+| `.pawnpro/config.json` | Projeto (sobrescreve o global) |
+| `.pawnpro/state.json` | Estado local (favoritos e histórico do servidor) |
+
+Nada disso precisa ser editado à mão: o painel de configurações cobre todas as
+chaves. A referência completa está em
+[docs/configuration.md](docs/configuration.md), e os comandos em
+[docs/commands.md](docs/commands.md).
+
+## Documentação
+
+| | |
+|---|---|
+| [Recursos](docs/features.md) | O que a extensão faz, em detalhe |
+| [Configuração](docs/configuration.md) | Todas as chaves |
+| [Comandos](docs/commands.md) | Paleta e atalhos |
+| [Servidor](docs/server.md) | Iniciar, RCON, favoritos e log |
+| [Depuração](docs/debugging.md) | Como configurar o depurador |
+| [Assistente de nomes](docs/naming-assistant.md) | Convenções e padrões próprios |
+
+Site completo: **[pawnpro.nullsablex.com](https://pawnpro.nullsablex.com)**
+
+## Como funciona por dentro
 
-Acesse o painel de configurações pelo item **PawnPro** na barra de status → **Configurações**, ou pelo comando `PawnPro: Configurações` na paleta de comandos.
+A análise não roda em JavaScript. É um processo separado —
+[**pawnpro-engine**](https://github.com/NullSablex/PawnPro-Engine), escrito em
+**Rust** — que conversa com o editor pelo protocolo LSP. Isso é o que permite
+analisar um gamemode grande com todos os seus includes sem travar a digitação.
 
-Para a referência completa de chaves, consulte [docs/configuration.md](docs/configuration.md).  
-Para a lista de comandos, consulte [docs/commands.md](docs/commands.md).
+A depuração segue o mesmo princípio: um adaptador DAP na extensão e um plugin
+dentro do servidor.
 
-## Notas
+## Bom saber
 
-- O monitoramento de log do servidor funciona apenas em **Linux e macOS**.
-- Firewalls/antivírus podem bloquear tráfego RCON (UDP) — libere a porta local se necessário.
-- `${workspaceFolder}` é substituído automaticamente em caminhos de configuração.
+- O acompanhamento de log do servidor funciona em **Linux e macOS**.
+- O RCON do SA-MP é um protocolo antigo, que trafega a senha em texto claro. Por
+  isso o envio direto vale só para servidor **local**; para um remoto, a extensão
+  usa o terminal. Firewalls podem bloquear a porta UDP local.
+- Comandos que pareçam carregar senha nunca são guardados no histórico.
 
 ## Contribuindo
 

docs/configuration.md

@@ -152,6 +152,10 @@ Observações:
     "clearOnStart": true,
     "output": {
       "follow": "visible"
+    },
+    "history": {
+      "enabled": true,
+      "sensitiveCommands": []
     }
   }
 }
@@ -167,6 +171,8 @@ Observações:
 | `server.logEncoding` | `"windows1252"` | Codificação do arquivo de log: `utf8`, `windows1250`–`windows1257` ou `latin1` |
 | `server.clearOnStart` | `true` | Limpa o painel de saída ao (re)iniciar o servidor |
 | `server.output.follow` | `"visible"` | Rola automaticamente o painel de log: `"visible"` (quando visível), `"always"` ou `"off"` |
+| `server.history.enabled` | `true` | Guarda em `.pawnpro/state.json` os comandos enviados ao servidor. `false` não registra nada. O arquivo é criado com permissão restrita ao seu usuário e não deve entrar no controle de versão |
+| `server.history.sensitiveCommands` | `[]` | Comandos do seu gamemode que recebem senha ou token e não devem ser guardados, além dos que a extensão já reconhece (`login`, `rcon_password`, `password`, `changepassword`, `setpassword`, e senha anunciada por rótulo como `--senha abc`). Comparados pelo primeiro termo, sem diferenciar maiúsculas |
 
 ## Interface e idioma
 
@@ -191,5 +197,6 @@ Observações:
 | `syntax.applyOnStartup` | `false` | Reaplicar o esquema ao iniciar (gerenciado automaticamente pelos comandos `applySyntaxScheme` e `resetSyntaxScheme`) |
 | `ui.showIncludePaths` | `false` | Exibe o caminho relativo de cada arquivo `.inc` na aba Includes da barra lateral |
 | `ui.animateTitle` | `false` | Anima as letras do título PawnPro no topo das páginas em sequência (teclado → bloco → cair), em loop com pausa |
+| `ui.accent` | `""` | Cor de destaque das páginas da extensão (botões, item ativo, foco, badges): `""` (automático, herda do tema do editor), `"blue"`, `"purple"`, `"green"`, `"amber"`, `"pink"` ou `"teal"`. Não altera o realce de sintaxe |
 | `ui.locale` | `""` | Idioma das **páginas da extensão** (Configurações, Ajuda, O que há de novo): `""` (automático, segue o editor), `"pt-BR"`, `"en"`, `"es"`, `"ro"` ou `"ru"`. Independente de `locale` |
 | `locale` | `""` | Idioma dos **diagnósticos** do motor LSP e do debugger: `""` (automático, segue o editor), `"pt-BR"`, `"en"`, `"es"`, `"ro"` ou `"ru"` |

docs/debugging.md

@@ -101,6 +101,32 @@ Pronto — isso é feito **uma única vez** por servidor.
 A extensão recompila com `-d3`, verifica o plugin, sobe o servidor e conecta.
 Ao atingir um breakpoint, a execução pausa e você vê as **variáveis** em escopo.
 
+### O que dá para fazer na pausa
+
+- **Percorrer a pilha de chamadas** — a lista de frames mostra quem chamou quem;
+  clicar em um frame faz a inspeção seguir para ele.
+- **Inspecionar arrays e strings** — arrays expandem elemento a elemento, e um
+  array de char é mostrado como texto quando o conteúdo é uma string.
+- **Avaliar expressões** no watch e no hover: aritmética (`+ - * / %`, com o
+  truncamento do Pawn) e comparação (`== != < > <= >=`) sobre literais,
+  variáveis e `arr[i]`. O console e o watch sugerem as variáveis em escopo.
+- **Editar valores** — `x = 1` ou `arr[i] = 10`. O array inteiro não é editável,
+  só os elementos.
+- **Ler a memória** — hex view da memória de dados a partir de qualquer variável.
+
+### Tipos de breakpoint
+
+Além do breakpoint de linha (**condicional**, por **contagem de acertos** e
+**logpoint**):
+
+- **Data breakpoint** — pausa quando um valor muda, seja global, local ou um
+  elemento de array (`arr[3]`). Watches de variáveis locais expiram quando a
+  função dona retorna.
+- **Breakpoint de função** — para ao entrar numa função pelo nome.
+- **Pausa em erro de runtime** — divisão por zero, índice de array fora do
+  limite, colisão entre pilha e heap, underflow de heap e acesso inválido à
+  memória. Liga e desliga pelo painel de breakpoints.
+
 A **saída do servidor** (incluindo `print` e logs do gamemode) aparece no painel
 **Console de Depuração** do editor — não é preciso abrir um terminal à parte.
 
@@ -134,9 +160,10 @@ Mesmo que você escolha iniciar assim mesmo, a depuração só funciona com o pl
 correto: um plugin homônimo não abre o canal de depuração, então o adaptador
 falha ao conectar com uma mensagem explicando as causas prováveis.
 
-## Limitações (v1)
+## Limitações
 
 - **Alvo é desenvolvimento local.** Não é para servidor de produção com jogadores.
 - O `.amx` precisa ter sido compilado com `-d3` (a extensão cuida disso).
 - Sem *hot-reload* / *edit-and-continue*.
-- **Call stack ainda mostra só o frame atual** (não percorre a cadeia de chamadas).
+- Nas expressões do watch e do hover, um operador de topo por vez — sem
+  encadear várias operações na mesma expressão.