Proveniência e Autoria: Este documento integra o projeto Mahoraga (licença MIT-0).

Índice

• Começar Rápido (30 segundos)
• Fluxo Passo a Passo
• Funcionalidades
• Instalação
• Configuração
• Comandos da CLI
• REST API
• SDK Programático
• GitHub App
• Editor (LSP / VSCode)
• CI/CD
• Linguagens Suportadas
• Documentação Completa
• Desenvolvimento
• Contribuir
• Licença

Começar Rápido (30 segundos)

# 1. Instalar
npm install -g mahoraga

# 2. Analisar seu projeto
cd meu-projeto
mahoraga diagnosticar

# 3. Ver problemas críticos
mahoraga diagnosticar --gravidade critic

# 4. Exportar relatório
mahoraga diagnosticar --relatorio json --saida relatorio.json

Próximos passos imediatos:

# Revisar correções disponíveis
mahoraga corrigir --revisar

# Aplicar correções automáticas seguras
mahoraga corrigir --auto

# Estabelecer baseline de saúde (assinatura GPG)
mahoraga guardian --accept-baseline

# Verificar mudanças
mahoraga guardian

Fluxo Passo a Passo

O Mahoraga foi projetado para guiar você por um fluxo completo de análise e manutenção do seu projeto:

Passo 1: Diagnóstico Inicial

Analise todo o projeto para identificar problemas de qualidade, segurança e arquitetura:

# Análise completa
mahoraga diagnosticar

# Mais detalhes
mahoraga diagnosticar --verbose

# Apenas críticos
mahoraga diagnosticar --gravidade critic

# Exportar resultados
mahoraga diagnosticar --relatorio json --saida analise.json
mahoraga diagnosticar --relatorio markdown --saida RELATORIO.md

Passo 2: Estabelecer Baseline

Crie um baseline criptográfico com assinaturas GPG do projeto para monitorar mudanças:

mahoraga guardian --accept-baseline

Passo 3: Corrigir Problemas

Aplique correções automáticas com segurança:

# Revisar o que pode ser corrigido
mahoraga corrigir

# Aplicar correções automáticas
mahoraga corrigir --auto

# Corrigir tipos inseguros
mahoraga fix-types --auto

Passo 4: Organizar com Sugestões e Barrels

Revise sugestões estruturais e organize os barrels do projeto:

# Ver sugestões de reorganização (apenas sugestões, sem modificações)
mahoraga diagnosticar --export --export-to ./sugestoes

# Gerar barrels estruturados (index.ts)
mahoraga barrels --scan          # preview do que será criado
mahoraga barrels --generate      # criar/atualizar barrels

# Remover arquivos órfãos
mahoraga podar

Passo 5: Monitoramento Contínuo

Mantenha a saúde do projeto ao longo do tempo:

# Verificar integridade contra baseline
mahoraga guardian

# Mostrar diferenças detalhadas
mahoraga guardian --diff

# Comparar performance
mahoraga perf snapshot --baseline
mahoraga perf compare

# Ver histórico de métricas
mahoraga metricas

Funcionalidades

Análise Inteligente

• Diagnóstico completo — qualidade, segurança e arquitetura
• 15+ detectores especializados — código frágil, duplicação, complexidade, performance, vazamentos de memória, tipos inseguros
• 18+ plugins multi-linguagem — React, CSS, HTML, Python, Shell, SQL, Tailwind, XML, SVG
• Detecção de bugs via ML — 8 padrões com pontuação Bayesiana (v0.10.0)
• Registro inteligente — descoberta automática de analistas built-in e customizados
• Análise de monorepos — pnpm-workspace, lerna, nx, turbo (v0.10.0)

Manutenção Assistida

• Auto-fix seguro — correções automáticas com validação (corrigir)
• Guardian — monitoramento contínuo com assinatura GPG, baselines criptográficos e verificação de integridade
• Reestruturação — reorganização automática seguindo padrões arquiteturais
• Poda inteligente — identificação e remoção de arquivos órfãos e código morto
• Fix Types — correção automática de any e unknown
• Formatação — formatação automática do código
• Names/Rename — extração e renomeação em massa de variáveis
• Reverter — rollback de movimentações aplicadas

Relatórios Profissionais

• Múltiplos formatos — JSON, Markdown, HTML, CSV com sharded export
• Métricas detalhadas — complexidade ciclomática, duplicação, cobertura, performance com histórico
• Baseline de performance — snapshots e comparação ao longo do tempo
• Scan de licenças — verificação de dependências e geração de THIRD-PARTY-NOTICES
• Relatórios de compliance — ISO 27001, SOC 2
• Streaming — NDJSON sharded com gzip para projetos grandes (v0.10.0)

Extensível

• Plugin system — crie analistas customizados com autodiscovery
• API modular — use como biblioteca (mahoraga/sdk)
• REST API — servidor HTTP com Swagger UI
• Worker pool — processamento paralelo para projetos grandes
• Marketplace — analistas comunitários

Integrações

• GitHub App — análise automática de workflows em PRs e pushes
• GitHub Actions — scan de workflows, score 0-100, check runs
• GitLab CI / CircleCI / Jenkins / Azure Pipelines — análise de pipelines
• LSP — diagnóstico em tempo real para editores
• VSCode Extension — análise ao salvar/abrir arquivos

Instalação

npm (Recomendado)

Uso global:

npm install -g mahoraga
mahoraga --version

Uso local no projeto:

npm install --save-dev mahoraga
npx mahoraga --help

Do Repositório

git clone https://github.com/um-atoa/mahoraga.git
cd mahoraga
npm install
npm run build
npm link

Docker

docker build -t mahoraga .
docker run --rm -v $(pwd):/project mahoraga diagnosticar

Verificar Instalação

mahoraga --version       # v0.10.2
mahoraga --help          # lista todos os comandos
mahoraga analistas --listar  # analistas disponíveis

Configuração

O Mahoraga lê um arquivo mahoraga.config.json na raiz do seu projeto. Se não existir, usa configurações padrão sensatas.

Configuração Mínima

{
  "locale": "pt",
  "verbose": true,
  "exclude": ["node_modules/**", "dist/**", "coverage/**", ".git/**"],
  "languageSupport": {
    "javascript": { "enabled": true },
    "typescript": { "enabled": true },
    "html": { "enabled": true },
    "css": { "enabled": true }
  }
}

Blocos Principais

| Bloco | Descrição | |-------|-----------| | locale | Idioma (pt, en, zh, ja) | | verbose | Saída detalhada | | logLevel | Nível de log (debug, info, warn, error) | | safeMode | Modo seguro (sem operações destrutivas) | | exclude | Glob patterns para exclusão | | INCLUDE_EXCLUDE_RULES | Regras globais de inclusão/exclusão | | languageSupport | Configuração por linguagem | | rules | Customização de severidade por regra | | suppress | Supressão de avisos por regra/caminho | | testPatterns | Padrões para detecção de testes | | analystsExclude | Analistas a desabilitar | | GUARDIAN_* | Configurações do Guardian (assinatura GPG) | | REPORT_* | Configurações de relatórios | | WORKER_POOL_* | Pool de workers paralelos | | PLUGINS | Sistema de plugins | | CACHE_STRATEGY | Estratégia de cache |

Variáveis de Ambiente

| Variável | Descrição | Padrão | |----------|-----------|--------| | MAHORAGA_API_PORT | Porta da API | 3100 | | MAHORAGA_API_CORS_ORIGINS | Origens CORS | localhost: 00 | | LOG_LEVEL | Nível de log | info | | LOG_ESTRUTURADO | Logs em JSON | false | | MAHORAGA_DEBUG | Modo debug | — | | GITHUB_APP_ID | ID do GitHub App | — | | GITHUB_PRIVATE_KEY | Chave RSA do GitHub App | — | | GITHUB_WEBHOOK_SECRET | Webhook secret | — |

[BOOK] Guia de Configuração Completo →

Comandos da CLI

Comandos Principais

| Comando | Descrição | Exemplo | |---------|-----------|---------| | diagnosticar | Análise completa do projeto | mahoraga diagnosticar --verbose | | corrigir | Auto-fix com validação | mahoraga corrigir --auto | | guardian | Monitoramento contínuo | mahoraga guardian --baseline | | reestruturar | Reorganizar estrutura do código | mahoraga reestruturar --auto | | podar | Remover código morto | mahoraga podar | | fix-types | Corrigir tipos inseguros | mahoraga fix-types --auto | | formatar | Formatação automática | mahoraga formatar --write | | analistas | Listar analistas | mahoraga analistas --listar |

Diagnóstico Avançado

mahoraga diagnosticar --full               # análise completa
mahoraga diagnosticar --fast               # modo rápido
mahoraga diagnosticar --compact            # saída compacta
mahoraga diagnosticar --json               # saída JSON
mahoraga diagnosticar --stream             # streaming para projetos grandes
mahoraga diagnosticar --executive          # relatório executivo
mahoraga diagnosticar --monorepo           # análise de monorepo
mahoraga diagnosticar --guardian-check     # verificar Guardian
mahoraga diagnosticar --include "src/**"   # incluir padrão
mahoraga diagnosticar --exclude "**/*.test.ts"  # excluir padrão
mahoraga diagnosticar --path ./frontend --path ./backend  # múltiplos diretórios

Correção e Manutenção

mahoraga corrigir --revisar        # revisar antes de aplicar
mahoraga corrigir --auto           # aplicar automaticamente
mahoraga corrigir --tipo variavel-nao-usada  # tipo específico
mahoraga fix-types --dry-run       # simular correção
mahoraga fix-types --target src    # diretório alvo

Guardian (Monitoramento com GPG)

O Guardian utiliza assinatura GPG (Ed25519) em vez de hashes convencionais para garantir a integridade dos arquivos. Cada baseline armazena assinaturas criptográficas individuais, permitindo autenticação e não-repúdio.

mahoraga guardian                   # verificar integridade
mahoraga guardian --accept-baseline # aceitar estado atual como baseline
mahoraga guardian --diff            # mostrar diferenças
mahoraga guardian --full-scan       # scan completo sem ignorar padrões
mahoraga guardian --json            # saída JSON estruturada

Como funciona:

1. Chaves — um par de chaves GPG (Ed25519) é gerado automaticamente em .mahoraga/
2. Baseline — cada arquivo é assinado com a chave privada; a assinatura é armazenada no baseline
3. Verificação — a assinatura armazenada é verificada contra o conteúdo atual usando a chave pública
4. Drift — arquivos adicionados, removidos ou com assinatura inválida são detectados

As chaves GPG ficam em .mahoraga/ e são automaticamente excluídas do versionamento (.gitignore).

Nomes e Renomeação

mahoraga names                     # extrair nomes de variáveis
mahoraga rename --apply            # aplicar renomeações
mahoraga reverter listar           # listar reversões
mahoraga reverter move <id>        # reverter movimento específico

Licenças e Compliance

mahoraga licencas scan                          # scan de licenças
mahoraga licencas notices generate              # gerar THIRD-PARTY-NOTICES
mahoraga licencas disclaimer add                # adicionar disclaimer
mahoraga licencas disclaimer verify             # verificar disclaimers
mahoraga compliance report iso-27001            # relatório ISO 27001
mahoraga compliance report soc2 --json          # relatório SOC 2

CI/CD

mahoraga github-actions scan                    # scan de workflows
mahoraga github-actions report --format html    # relatório HTML
mahoraga github-actions gate --threshold 80     # quality gate
mahoraga gitlab-ci scan                         # scan GitLab CI
mahoraga circleci scan                          # scan CircleCI
mahoraga jenkins scan                           # scan Jenkins
mahoraga azure scan                             # scan Azure Pipelines

Métricas e Performance

mahoraga metricas                               # histórico de métricas
mahoraga metricas --analistas                   # métricas por analista
mahoraga perf snapshot --baseline               # baseline de performance
mahoraga perf compare                           # comparar performance

Utilitários

mahoraga otimizar-svg --write                   # otimizar SVGs
mahoraga atualizar                              # atualizar Mahoraga
mahoraga plugins list                           # listar plugins
mahoraga marketplace search                     # buscar analistas
mahoraga vulnerabilidades scan                  # scan de vulnerabilidades
mahoraga formatters list                        # listar formatadores
mahoraga lsp                                    # iniciar servidor LSP
mahoraga serve --port 3100                      # iniciar REST API
mahoraga convert                                # converter projeto
mahoraga imports --scan                         # gerenciar imports

[BOOK] Guia de Comandos Completo →

REST API

O Mahoraga pode ser executado como um servidor HTTP RESTful para integração com outras ferramentas.

# Iniciar servidor
mahoraga serve --port 3100

Base URL: http://localhost:3100/api/v1 Swagger UI: http://localhost:3100/api/docs

Endpoints

| Endpoint | Método | Descrição | |----------|--------|-----------| | /api/health | GET | Health check | | /api/v1/analistas | GET | Listar analistas | | /api/v1/analistas/stats | GET | Estatísticas | | /api/v1/diagnosticar | POST | Executar diagnóstico | | /api/v1/diagnosticar/jobs | GET | Listar jobs | | /api/v1/diagnosticar/jobs/:id | GET | Status do job | | /api/v1/guardian | GET | Status do Guardian | | /api/v1/guardian/baseline | POST | Criar baseline | | /api/v1/guardian/diff | GET | Comparar baseline | | /api/v1/metricas | GET | Métricas históricas |

Exemplo

# Diagnóstico assíncrono
curl -X POST http://localhost:3100/api/v1/diagnosticar \
  -H "Content-Type: application/json" \
  -d '{"async": true, "fast": true}'

[BOOK] Documentação da API →

SDK Programático

Use o Mahoraga como biblioteca no seu código:

npm install mahoraga

import { analyzeFile, analyzeProject } from 'mahoraga/sdk'

// Analisar um arquivo
const result = await analyzeFile('/caminho/arquivo.ts', conteudo)

// Analisar projeto inteiro
const projeto = await analyzeProject('/caminho/projeto')

import { MahoragaSDK } from 'mahoraga/sdk'

const sdk = new MahoragaSDK()
await sdk.analisarGithubActions('./.github/workflows')
sdk.registrarDetector('meu-detector', meuDetector)

Subpath exports:

| Import Path | Descrição | |-------------|-----------| | mahoraga | Entry principal | | mahoraga/sdk | SDK programático | | mahoraga/api | REST API server | | mahoraga/types | Typescript types | | mahoraga/bin | CLI binary |

GitHub App

O Mahoraga pode operar como um GitHub App que analisa automaticamente workflows do GitHub Actions em PRs, pushes e issues.

Funcionalidades

• Análise automática de workflows em PRs e pushes
• Score de qualidade 0-100 para cada workflow
• Detecção de script injection, secrets hardcoded, permissões excessivas
• Comentários automáticos em PRs e issues
• Check runs com annotations no código
• Análise sob demanda via @mahoraga analyze em reviews
• Scan sob demanda via @mahoraga scan em issues

Eventos Suportados

| Evento | Comportamento | |--------|---------------| | Check Suite | Cria check run com análise completa | | Pull Request | Posta comentário detalhado | | Push | Análise silenciosa | | Review | Responde a @mahoraga analyze | | Issues | Responde a @mahoraga scan |

Comandos

mahoraga github-actions scan                    # scan local
mahoraga github-actions report --format html    # relatório
mahoraga github-actions gate --threshold 80     # quality gate
mahoraga github-actions app --port 3000         # iniciar servidor

[BOOK] Guia do GitHub App →

Editor (LSP / VSCode)

LSP Server

mahoraga lsp

Suporta textDocument/didOpen, didChange, didSave para diagnóstico em tempo real.

VSCode Extension

Uma extensão VSCode está disponível em extensions/vscode/ com:

• Análise ao salvar (mahoraga.runOnSave)
• Análise ao abrir (mahoraga.runOnOpen)
• Painel de resultados
• Comandos: Analyze File, Analyze Project, Show Panel, Clear Diagnostics

[BOOK] Guia VSCode →

CI/CD

O Mahoraga analisa pipelines de CI/CD para detectar problemas de segurança, performance e boas práticas.

| Plataforma | Comando | |------------|---------| | GitHub Actions | mahoraga github-actions scan | | GitLab CI | mahoraga gitlab-ci scan | | CircleCI | mahoraga circleci scan | | Jenkins | mahoraga jenkins scan | | Azure Pipelines | mahoraga azure scan |

# Quality gate para CI (falha se score < 80)
mahoraga github-actions gate --threshold 80 --fail-on erro

Linguagens Suportadas

| Linguagem | Parser | Status | |-----------|--------|--------| | JavaScript | Babel | Nativo | | TypeScript | Babel | Nativo | | HTML | htmlparser2 | Nativo | | CSS | css-tree | Nativo | | XML | fast-xml-parser | Nativo | | Python | Heurístico | Nativo | | PHP | Heurístico | Nativo | | Shell | Heurístico | Plugin | | SQL | Heurístico | Plugin | | Go | Heurístico | Nativo (v0.8.0) | | Rust | Heurístico | Nativo (v0.8.0) | | Java | java-parser | Disponível | | Kotlin | Heurístico | Disponível |

Documentação Completa

Guias

• Guia de Início Rápido — tutorial de 10 minutos
• Guia de Configuração — personalizar setup
• Guia de Comandos — referência completa
• Guia Marketplace — analistas comunitários
• Guia VSCode — extensão VSCode
• Guia Compliance — ISO 27001, SOC 2
• Guia Formatters — plugins de saída

Arquitetura

• Árvore Arquitetural — estrutura visual
• Type Safety — garantias de tipo
• Segurança — práticas de segurança
• Sistema de Erros — tratamento de erros

Desenvolvimento

• Criar Analistas — guia de 6 passos
• Estrutura do Código — mapa do src/
• Padrões de Desenvolvimento — convenções
• Sistema de Plugins — como estender

Referência

• REST API — documentação da API v1
• Exemplos de Uso — casos reais e CI/CD
• Roadmap — futuro do projeto
• Índice Completo — navegação por tópico

Desenvolvimento

Setup

git clone https://github.com/um-atoa/mahoraga.git
cd mahoraga
npm install
npm run build
npm link
mahoraga --version

Scripts

npm run build          # compilar TypeScript
npm run typecheck      # verificar tipos
npm run lint           # ESLint
npm run test           # testes (Vitest)
npm run coverage       # cobertura de testes
npm run start          # executar Mahoraga
npm run diagnosticar   # auto-análise

Qualidade

• TypeScript 6.0+ — type-safe, sem any desnecessários
• Testes com Vitest — cobertura target > 90%
• ESLint 9.x — configuração strict
• Worker Pool — processamento paralelo
• Schema Versioning — relatórios versionados
• i18n — PT, EN, ZH, JA
• CodeQL — segurança auditada

Padrões

• TypeScript type-safe (sem any ou unknown sem necessidade)
• Nomes descritivos em camelCase/PascalCase
• Testes com cobertura > 90%
• Sem console.log em produção (use sistema de mensagens)
• Imports organizados e ordenados
• Padrões arquiteturais (Registry, Strategy, Singleton)

Contribuir

1. Leia CONTRIBUTING.md
2. Fork o repositório
3. Crie branch: git checkout -b feature/sua-feature
4. Commit: git commit -m 'Add: sua feature'
5. Push: git push origin feature/sua-feature
6. Abra Pull Request

Áreas para Contribuir

• Bug fixes — reportar e corrigir bugs
• Novas features — analistas, comandos, plugins
• Documentação — guias, exemplos
• Testes — aumentar cobertura
• Analisadores — criar detectores e plugins

[BOOK] Guia: Como Criar Analistas →

Licença

Mahoraga é licenciado sob MIT-0 (MIT No Attribution).

• Sem restrições de uso, modificação ou distribuição
• Sem atribuição necessária (mas apreciada!)
• Sem garantias

Dependências de terceiros listadas em THIRD-PARTY-NOTICES.txt.

Feito para os iniciantes — Voltar ao topo

mahoraga

mahoraga

mahoraga