Code Guardian — Manual de Uso

Visão Geral

O Code Guardian UI é uma interface gráfica que encapsula todos os scripts de análise do Code Guardian, permitindo executar revisões de código sem precisar usar o terminal. Construída em Python com customtkinter (tema escuro moderno).

Análise de projetos C# via runner.py (diff, staged, arquivo ou scan)

Análise de projetos VB6 via vb6_rule_engine.py (arquivo, scan ou comparação)

Terminal integrado com saída colorida em tempo real

Geração de relatórios HTML com um clique

Configuração visual de provedores de IA (Gemini, Claude, OpenAI, Ollama)

Instalação automática de dependências na primeira execução

Representação visual da interface:

┌─────────────────────────────────────────────────────────────────────┐
│  Code Guardian  v1.0.0                                              │
├──────────────────────────┬──────────────────────────────────────────┤
│  [ C# ]  [ VB6 ]         │  TERMINAL                                │
│  ┌────────────────────┐  │  [14:32:01] Executando: runner.py...     │
│  │ Modo de Análise    │  │  [14:32:02] Analisando (1/3): X.cs       │
│  │ ◉ Diff vs branch  │  │  🟡 L45 [Magic Number]...                │
│  │ ○ Staged          │  │  ✅ Análise concluída.                   │
│  │ ○ Arquivo único   │  │                                          │
│  │ ○ Scan de pasta   │  │                                          │
│  └────────────────────┘  │                                          │
├──────────────────────────┴──────────────────────────────────────────┤
│  [Executar]  [Abrir Relatório]  [Limpar Terminal]  [Configurações]  │
└─────────────────────────────────────────────────────────────────────┘

Pré-requisitos

Requisito	Versão mínima	Observação
Python	`3.10+`	Deve estar no PATH do sistema
Git	qualquer	Necessário para modos diff e staged
customtkinter	`5.2+`	Instalado automaticamente na 1ª execução
Pillow	qualquer	Instalado automaticamente na 1ª execução

Modo executável (.exe) Python precisa estar instalado no sistema do usuário mesmo ao usar o executável pré-compilado, pois os scripts de análise são invocados em subprocessos.

Instalação e Primeira Execução

Como script Python

Execute o comando abaixo na raiz do repositório:

bash

python .claude/scripts/code_guardian/code_guardian_ui.py

Na primeira execução, uma tela de instalação automática é exibida com barra de progresso enquanto as dependências customtkinter e Pillow são instaladas via pip.

Como executável (.exe)

Basta abrir CodeGuardian.exe. Nenhuma etapa adicional de instalação é necessária — as dependências Python já estão embutidas no executável.

Dica: primeira execução Certifique-se de abrir o terminal (ou o executável) com a pasta raiz do repositório como diretório de trabalho. Os scripts utilizam caminhos relativos a partir da raiz do projeto.

Layout da Interface

A janela é dividida em quatro áreas principais:

Área	Localização	Função
Painel de configuração	Esquerda (~430px fixo)	Abas C# e VB6 com todos os controles de análise
Terminal de saída	Direita (expansível)	Output colorido em tempo real dos scripts
Barra de ação	Parte inferior	Botões Executar, Abrir Relatório, Limpar Terminal e Configurações
Status bar	Rodapé	Exibe o repositório detectado e o estado atual da execução

Aba C# — Modos de Análise

A aba C# oferece quatro modos de análise, cada um adequado a um momento diferente do fluxo de trabalho:

Diff vs branch RECOMENDADO

Analisa apenas os arquivos .cs que foram alterados em relação a uma branch base. Usa git diff para identificar exatamente quais linhas mudaram.

Branch base: Branch de comparação (padrão: origin/main)
Raiz do projeto: Pasta raiz do repositório (preenchida automaticamente se a UI já estiver na raiz)

Ideal para: pull requests e revisão antes de push.

Staged

Analisa apenas os arquivos adicionados ao index via git add. Permite revisar exatamente o que será commitado.

Raiz do projeto: Obrigatório quando a UI está em pasta diferente do repositório analisado

Ideal para: revisão imediata antes de cada commit.

Atenção — modo Staged O comando git diff --cached precisa ser executado dentro do repositório correto. Se a UI estiver em pasta diferente do projeto analisado, defina o campo Raiz do projeto com o caminho completo do repositório.

Arquivo único

Analisa um único arquivo .cs selecionado via seletor de arquivos. Útil para inspeção pontual de uma classe ou serviço específico.

Arquivo .cs: Selecionado via diálogo de abertura de arquivo (filtro automático *.cs)

Ideal para: auditoria pontual, onboarding de código legado.

Scan de diretório

Varre todos os arquivos .cs de uma pasta recursivamente. Exclui automaticamente pastas que não contêm código relevante.

Pasta: Selecionada via diálogo de pasta

Ideal para: auditoria completa do projeto, CI/CD.

Exclusões automáticas no modo Scan O scanner ignora automaticamente os diretórios Migrations/, arquivos *.Designer.cs, e as pastas bin/ e obj/, evitando falsos positivos em código gerado automaticamente.

Opções C#

Apenas regras (sem IA)

Executa somente o rule_engine.py, sem chamar provedores de IA. Análise mais rápida.

Severidade mínima

Filtra issues pelo nível mínimo de severidade. Ver tabela abaixo.

Falhar em

Define o nível a partir do qual a execução retorna exit code 1 (útil em CI/CD).

Timeout

Tempo máximo em segundos para a análise de IA por arquivo. Padrão: 60s.

Saída HTML

Gera relatório HTML estilizado ao final da análise, acessível pelo botão Abrir Relatório.

Provedor de IA

Seleciona o provedor ativo: Gemini, Claude, OpenAI ou Ollama (local).

Tabela de severidade

Valor	O que inclui na saída
`info`	Todos os issues (padrão recomendado)
`warning`	Warnings, errors e criticals
`error`	Errors e criticals apenas
`critical`	Apenas issues críticos

Aba VB6 — Modos de Análise

A aba VB6 utiliza o vb6_rule_engine.py para aplicar mais de 20 regras de análise estática em arquivos legados VB6, retornando um score de 0 a 100.

Arquivo único

Analisa um único arquivo VB6 selecionado.

Extensões suportadas: .bas, .cls, .frm, .ctl

Ideal para: inspeção pontual de um módulo ou formulário.

Scan de diretório

Varre todos os arquivos VB6 de uma pasta recursivamente, gerando um relatório consolidado.

Pasta: Qualquer pasta contendo módulos VB6

Ideal para: auditoria completa de projetos legados.

Comparação de pastas VB6 EXCLUSIVO

Compara duas versões do mesmo projeto VB6, identificando arquivos novos, removidos e alterados, aplicando a análise de regras apenas nas diferenças.

Pasta base: Versão original do projeto (antes das alterações)
Pasta revisão: Versão modificada do projeto (após as alterações)

Ideal para: homologação de alterações VB6, validação de entregas.

Formato de saída

Valor	Comportamento
`text + html`	Saída colorida no terminal + relatório HTML (padrão recomendado)
`json`	JSON estruturado para consumo por outras ferramentas
`html`	Apenas relatório HTML, sem saída no terminal

Terminal de Saída

O terminal integrado exibe a saída dos scripts em tempo real, com colorização semântica para facilitar a leitura dos resultados.

[14:32:01] Iniciando análise — modo: diff vs origin/main
ℹ  Arquivos alterados detectados: 3
[14:32:02] Analisando (1/3): Services/UserService.cs
⚠  L45  [MagicNumber]        Número mágico: 86400 — extrair para constante
⚠  L78  [DeepNesting]        Nesting level 4 — refatorar método
[14:32:04] Analisando (2/3): Controllers/UserController.cs
✓  Nenhum issue encontrado.
[14:32:05] Analisando (3/3): Repositories/UserRepository.cs
✖  L22  [SQLInjection]        Concatenação direta em query SQL
ℹ  Risk Score: 72/100
✅ Análise concluída. Relatório gerado em: reports/review_20260319.html

Legenda de cores

Cor	Significado
Verde	Sucesso — arquivo sem problemas ou análise concluída
Laranja	Avisos (warning) — melhorias recomendadas
Vermelho	Erros críticos — issues de segurança ou qualidade graves
Azul	Informações gerais — contagens, scores, metadados
Cinza	Timestamps e metadados secundários

Botões de Ação

Executar / Cancelar

Inicia a análise com as configurações atuais. Durante a execução, o botão muda para Cancelar — clique para interromper o processo em andamento.

Abrir Relatório

Abre o relatório HTML gerado no navegador padrão do sistema. Habilitado automaticamente após análise com opção de saída HTML ativada.

Limpar Terminal

Limpa todo o conteúdo do terminal de saída, sem afetar a configuração atual nem interromper análises em andamento.

Configurações

Abre o diálogo de configuração de provedores de IA. Permite definir chaves de API, URL do Ollama e provedor primário/fallback.

Configurações de IA

O diálogo de configurações permite definir qual provedor de IA será usado para enriquecer a análise com sugestões contextuais, além das regras estáticas do rule_engine.py.

┌──────────────────────────────────────────┐
│  Configurações de IA                      │
├──────────────────────────────────────────┤
│  Provedor primário:  [ Gemini      ▾ ]  │
│  Provedor fallback:  [ Ollama      ▾ ]  │
│                                          │
│  Gemini                                   │
│  API Key: ••••••••••••••••••••••••••     │
│  Modelo:  gemini-1.5-pro               │
│                                          │
│  Claude                                   │
│  API Key: ••••••••••••••••••••••••••     │
│  Modelo:  claude-sonnet-4-6            │
│                                          │
│  OpenAI                                   │
│  API Key: ••••••••••••••••••••••••••     │
│  Modelo:  gpt-4o                       │
│                                          │
│  Ollama (local)                           │
│  URL:     http://localhost:11434       │
│  Modelo:  qwen2.5-coder:32b            │
│                                          │
│         [ Salvar ]  [ Cancelar ]         │
└──────────────────────────────────────────┘

Provedores disponíveis

Provedor	Tipo	Requisito	Observação
Gemini	Cloud	Chave `GEMINI_API_KEY`	Provedor padrão recomendado
Claude	Cloud	Chave `ANTHROPIC_API_KEY`	Alta qualidade de análise
OpenAI	Cloud	Chave `OPENAI_API_KEY`	Modelo padrão: gpt-4o
Ollama	Local	Ollama instalado e rodando	Privacidade total — sem envio de código para a nuvem

Localização do `config.json`

Modo de execução	Caminho do config.json
Script Python	`.claude/scripts/code_guardian/config.json`
Executável .exe	`%APPDATA%\CodeGuardian\config.json`

Dica: Ollama para ambientes offline Para análise sem acesso à internet ou em ambientes com restrição de envio de código, configure o provedor primário como ollama e o fallback como none. O modelo qwen2.5-coder:32b oferece excelente qualidade para análise de código.

Distribuição como .exe

Para gerar o executável Windows, execute o script de build na raiz do repositório:

bash

python .claude/scripts/code_guardian/build_exe.py

O processo utiliza PyInstaller internamente. O arquivo gerado é salvo em dist/CodeGuardian.exe.

O que está embutido no executável

Componente	Incluído no .exe
Interface gráfica (customtkinter)	Sim
Scripts de análise Python	Sim
Runtime Python	Não — requer Python 3.10+ no sistema
config.json	Não — lido de `%APPDATA%\CodeGuardian\`
Relatórios HTML gerados	Não — salvos junto ao projeto analisado

Requisito obrigatório Python 3.10 ou superior deve estar instalado no sistema do usuário e presente no PATH. Os scripts de análise são invocados como subprocessos e não estão embutidos no binário do executável.

Troubleshooting

Problemas comuns e como resolvê-los:

Interface abre sem tema escuro (janela cinza padrão do Windows)

Causa customtkinter não está instalado ou está em versão incompatível

Solução Execute pip install customtkinter --upgrade e reinicie a aplicação

Erro "Python não encontrado" ao iniciar ou executar análise

Causa Python não está instalado ou não foi adicionado ao PATH do sistema

Solução Reinstale o Python em python.org marcando a opção "Add Python to PATH" durante a instalação

Modo Staged retorna "nenhum arquivo detectado" mesmo após git add

Causa A UI está sendo executada em pasta diferente do repositório git analisado

Solução Defina o campo Raiz do projeto com o caminho completo do repositório que contém os arquivos staged

Botão "Abrir Relatório" permanece desabilitado após a análise

Causa Formato de saída não inclui HTML, ou a análise falhou antes de gerar o arquivo

Solução Certifique-se de que o formato está configurado como text + html ou html, e verifique se a pasta de saída tem permissão de escrita

Análise inicia mas trava indefinidamente sem saída no terminal

Causa Timeout do provedor de IA excedido, ou provedor indisponível

Solução Clique em Cancelar, ative a opção "Apenas regras (sem IA)" para uma análise imediata, ou reduza o valor de Timeout nas opções

Ícone do CodeGuardian.exe aparece genérico ou incorreto no Windows

Causa Cache de ícones do Windows Explorer não foi atualizado após o build

Solução Execute no PowerShell como administrador: ie4uinit.exe -show ou reinicie o Windows Explorer via Gerenciador de Tarefas

1 Visão Geral

2 Pré-requisitos

3 Instalação e Primeira Execução

Como script Python

Como executável (.exe)

4 Layout da Interface

5 Aba C# — Modos de Análise

Opções C#

Tabela de severidade

6 Aba VB6 — Modos de Análise

Formato de saída

7 Terminal de Saída

Legenda de cores

8 Botões de Ação

9 Configurações de IA

Provedores disponíveis

Localização do config.json

10 Distribuição como .exe

O que está embutido no executável

11 Troubleshooting

Visão Geral

Pré-requisitos

Instalação e Primeira Execução

Layout da Interface

Aba C# — Modos de Análise

Aba VB6 — Modos de Análise

Terminal de Saída

Botões de Ação

Configurações de IA

Localização do `config.json`

Distribuição como .exe

Troubleshooting