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]  │
└─────────────────────────────────────────────────────────────────────┘

Formas de Uso

O Code Guardian pode ser usado de três formas independentes, todas usando o mesmo motor de análise Python (code_guardian/). Escolha a que melhor se encaixa no seu fluxo de trabalho — elas podem inclusive ser combinadas no mesmo repositório.

Interface Desktop (.exe / script)

Interface gráfica standalone com abas C# e VB6, terminal integrado e relatórios HTML. Não depende de IDE — abra o .exe ou rode o script Python.

Extensão Visual Studio

Integração nativa: Error List, Tool Window com histórico e tendência, exportação SARIF para CI/CD e git hooks instaláveis pelo próprio menu Tools.

Extensão VS Code

Painel dedicado na Activity Bar, análise automática ao salvar, e os mesmos comandos de análise (arquivo, projeto completo ou apenas o diff) via Command Palette.

Forma de uso	Melhor para	Seção
Interface Desktop	Quem não usa Visual Studio ou VS Code no dia a dia, ou quer revisar VB6 fora de uma IDE	Seção 4
Extensão Visual Studio	Times C# que já trabalham no Visual Studio e querem o resultado direto no Error List	Seção 12
Extensão VS Code	Quem usa VS Code no dia a dia e quer feedback ao salvar, sem trocar de janela	Seção 13

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.

Comparação de arquivos VB6 EXCLUSIVO

Compara duas versões de um único arquivo VB6 (original vs modificado). Mesma lógica da comparação de pastas, só que aplicada a um form ou módulo específico.

Arquivo original (base): Versão atual do arquivo
Arquivo modificado (revisão): Versão com as alterações

Ideal para: revisar um único form ou módulo de uma entrega pontual.

Opção: Apenas linhas alteradas (diff-only)

Disponível nos dois modos de comparação. Usa difflib (nativo do Python) para calcular quais linhas foram adicionadas ou substituídas na versão revisada, e reporta apenas os issues que caem nessas linhas — o restante do arquivo (código legado não tocado) é ignorado.

Reduz drasticamente o ruído de código legado Sem diff-only, um arquivo VB6 antigo pode reportar centenas de issues pré-existentes. Com diff-only ativado, só aparecem os issues introduzidos pela alteração — em arquivos grandes, isso costuma reduzir a contagem de dezenas ou centenas de issues para poucas unidades.

Score de qualidade (0–100)

Score	Classificação	Ação recomendada
90–100	Excellent	Aprovado
75–89	Good — melhorias pontuais	Aprovado com ressalvas
60–74	Moderate technical debt	Revisar warnings críticos antes de aprovar
40–59	High technical debt	Refatoração recomendada
0–39	Critical — não aprovar	Não aprovar

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.

Extensão Visual Studio

Integração nativa do Code Guardian ao Visual Studio — os resultados aparecem direto no Error List, num Tool Window dedicado com histórico e tendência, e podem ser exportados em SARIF para pipelines de CI/CD.

Análise do arquivo atual ou da solution completa

Análise incremental — só os arquivos alterados via git diff HEAD

AI Toggle — liga/desliga a análise por IA direto no painel

Filtros por severidade e por texto livre na lista de issues

Histórico de execuções com tendência (↑ piorou / ↓ melhorou / = estável)

Navegação por clique — abre o arquivo direto na linha do issue

Suprimir issue com inserção automática de // guardian: suppress RULE_ID

Exportação SARIF 2.1.0 para GitHub Actions e Azure DevOps

Instalação de git hooks pelo próprio menu Tools

Requisitos

Requisito	Detalhes
Visual Studio	2019 (16.x) ou 2022 (17.x) — Community, Professional ou Enterprise
Python	3.8 ou superior — no `PATH` ou configurado em Tools → Options
Scripts Code Guardian	A pasta `code_guardian/` deve existir na raiz do repositório aberto

Instalação e primeiro uso

Instale a extensão pelo arquivo .vsix ou pelo Visual Studio Marketplace
Copie a pasta code_guardian/ para a raiz do repositório, se ainda não estiver lá
Abra a solution — a extensão carrega automaticamente
Vá em Tools → Analyze Current File (Code Guardian), ou clique com o botão direito na solution → Analyze with Code Guardian
Veja os resultados no Error List e no painel Tools → Code Guardian

Comandos

Comando	Local	Descrição
Code Guardian	Menu Tools	Abre o Tool Window
Analyze Current File	Menu Tools	Analisa o arquivo `.cs` ativo
Analyze with Code Guardian	Solution Explorer (menu de contexto)	Scan completo da solution
Install Git Hooks	Menu Tools	Instala o hook pre-commit no repositório
Export SARIF	Tool Window	Exporta o resultado em SARIF 2.1.0

Configurações em Tools → Options → Code Guardian Python Executable, Runner Script Path, Analysis Timeout (padrão 60s) e Rules Only — os mesmos conceitos das configurações da interface desktop.

SARIF para CI/CD O arquivo gerado em .codeguardian/guardian-report.sarif pode ser consumido diretamente por github/codeql-action/upload-sarif no GitHub Actions ou por PublishBuildArtifacts no Azure DevOps.

Instalação e código-fonte da extensão: pasta CodeGuardian.VS/ no repositório do Code Guardian.

Extensão VS Code

Mesma engine de análise, agora dentro do VS Code — com um painel dedicado na Activity Bar e análise automática ao salvar arquivos .cs.

Painel próprio na Activity Bar (ícone de escudo)

Análise automática ao salvar (configurável)

Analisar arquivo atual, projeto completo ou apenas o diff

Exportação SARIF e instalação de git hooks via Command Palette

Configuração de provedor de IA (Gemini, Claude, OpenAI, Ollama) direto nas Settings

Requisitos

Requisito	Detalhes
VS Code	1.85 ou superior
Python	3.8 ou superior — no `PATH` ou configurado em `codeguardian.pythonExecutable`
Scripts Code Guardian	A pasta `code_guardian/` deve existir no workspace aberto

Comandos (Command Palette)

Comando	Descrição
Code Guardian: Analisar Arquivo Atual	Analisa o arquivo `.cs` aberto no editor
Code Guardian: Analisar Projeto Completo	Varre todos os arquivos `.cs` do workspace
Code Guardian: Analisar Alterações (git diff)	Analisa apenas o que mudou desde o último commit
Code Guardian: Abrir Painel	Abre o painel dedicado na Activity Bar
Code Guardian: Instalar Git Hooks	Instala o hook pre-commit no repositório
Code Guardian: Exportar SARIF	Exporta o resultado em SARIF 2.1.0
Code Guardian: Limpar Resultados	Limpa os resultados exibidos no painel

Configurações (Settings)

Configuração	Padrão	Descrição
`codeguardian.pythonExecutable`	`python`	Executável Python, se não estiver no PATH
`codeguardian.analyzeOnSave`	`true`	Analisar automaticamente ao salvar arquivos `.cs`
`codeguardian.rulesOnly`	`true`	Usar apenas regras, sem IA — análise mais rápida
`codeguardian.minimumSeverity`	`warning`	Severidade mínima exibida: info / warning / error / critical
`codeguardian.timeoutSeconds`	`30`	Timeout máximo da análise, em segundos
`codeguardian.ia.providerPrimary`	`ollama`	Provedor de IA principal
`codeguardian.ia.providerFallback`	`none`	Provedor de IA de fallback
`codeguardian.ia.ollamaUrl`	`http://localhost:11434`	URL do servidor Ollama local
`codeguardian.ia.ollamaModel`	`qwen2.5-coder:32b`	Modelo Ollama a usar

Padrão já é offline por padrão O provedor de IA primário já vem configurado como ollama (local) — não é preciso nenhuma chave de API para começar a usar a extensão.

Instalação e código-fonte da extensão: pasta CodeGuardian.VsCode/ no repositório do Code Guardian.

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 Formas de Uso

3 Pré-requisitos

4 Instalação e Primeira Execução

Como script Python

Como executável (.exe)

5 Layout da Interface

6 Aba C# — Modos de Análise

Opções C#

Tabela de severidade

7 Aba VB6 — Modos de Análise

Opção: Apenas linhas alteradas (diff-only)

Score de qualidade (0–100)

Formato de saída

8 Terminal de Saída

Legenda de cores

9 Botões de Ação

10 Configurações de IA

Provedores disponíveis

Localização do config.json

11 Distribuição como .exe

O que está embutido no executável

12 Extensão Visual Studio

Requisitos

Instalação e primeiro uso

Comandos

13 Extensão VS Code

Requisitos

Comandos (Command Palette)

Configurações (Settings)

14 Troubleshooting

Visão Geral

Formas de Uso

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

Extensão Visual Studio

Extensão VS Code

Troubleshooting