@mocoto/mahoraga 0.15.0 → 0.15.2

package/Docs/02-componentes/_index.md

@@ -0,0 +1,294 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [moc, componentes]
+created: 2026-07-24
+updated: 2026-07-25
+---
+
+# Componentes
+
+## src/bin/
+
+| Arquivo | Função |
+|---------|--------|
+| `index.ts` | Entry point. Loader ESM, handlers de erro, registro de comandos |
+
+## src/cli/
+
+Interface de linha de comando. Commander.js com 27 comandos.
+
+### commands/
+
+| Arquivo | Comando | Descrição |
+|---------|---------|-----------|
+| `command-diagnostic.ts` | `diagnosticar` / `diag` | Análise completa do projeto |
+| `command-guardian.ts` | `guardian` | Monitoramento de integridade GPG |
+| `command-formatters.ts` | `formatters` | Gerenciamento de formatadores |
+| `command-format.ts` | `formatar` | Formatação automática |
+| `command-otimizar-svg.ts` | `otimizar-svg` | Otimização de SVGs |
+| `command-podar.ts` | `podar` | Remoção de arquivos órfãos |
+| `command-atualizar.ts` | `atualizar` | Auto-update |
+| `command-fix-types.ts` | `fix-types` | Correção de tipos inseguros |
+| `command-analistas.ts` | `analistas` | Listagem de analistas/detectores |
+| `command-metricas.ts` | `metricas` | Métricas de execução |
+| `command-licencas.ts` | `licencas` | Scan de licenças e notices |
+| `command-vulnerabilities.ts` | `vulnerabilidades` | Scan de vulnerabilities |
+| `command-plugins.ts` | `plugins` | Gerenciamento de plugins |
+| `command-marketplace.ts` | `marketplace` | Marketplace de analistas |
+| `command-imports.ts` | `imports` | Gerenciamento de aliases |
+| `command-barrels.ts` | `barrels` | Gerenciamento de index.ts |
+| `command-names.ts` | `names` | Extração/renomeação de variáveis |
+| `command-reverter.ts` | `reverter` | Rollback de movimentações |
+| `command-compliance.ts` | `compliance` | Relatórios ISO 27001, SOC 2 |
+| `command-convert.ts` | `convert` / `conv` | Conversão entre CI/CD |
+| `command-github-actions.ts` | `github-actions` | Análise GitHub Actions |
+| `command-gitlab-ci.ts` | `gitlab-ci` | Análise GitLab CI |
+| `command-circleci.ts` | `circleci` | Análise CircleCI |
+| `command-jenkins.ts` | `jenkins` | Análise Jenkins |
+| `command-azure.ts` | `azure` | Análise Azure Pipelines |
+| `command-perf.ts` | `perf` | Snapshots de performance |
+
+### Outros diretórios
+
+| Diretório | Conteúdo |
+|-----------|----------|
+| `diagnostic/` | Opções e processamento de diagnóstico |
+| `handlers/` | Handlers auxiliares (vulnerabilidades, etc.) |
+| `helpers/` | Exit codes, processPatternList, sair |
+| `options/` | Opções compartilhadas entre comandos |
+
+## src/core/
+
+Motor central do sistema.
+
+### execution/
+
+Scanner principal, registry de arquivos, executor de análise, cache (analysis, AST), inquisitor, linguagens, parse-errors, schema, structure-json, worker pool integration.
+
+### config/
+
+Configuração central: defaults, scoring, conventions, excludes, filters, paths, security, chalk-safe, include-exclude, traverse, format, auto-fix.
+
+### parsing/
+
+Parsers baseados em Babel (babel-narrow) + parsers por linguagem em `langs/`. Filtros, plugins, utils.
+
+### messages/
+
+Sistema de i18n organizado por idioma (`pt/`, `en/`, `zh/`, `ja/`) e por domínio (`cli/`, `github/`, `analysts/`, etc.). Cada pasta contém subpastas para cada módulo que possui mensagens. Ícones compartilhados em `icons/`.
+
+### workers/
+
+Worker pool para processamento paralelo. Gerencia fila de tarefas, workers, resultados.
+
+### Correção e Formatação
+
+- `corrections/`: Auto-fix engine
+- `formatters/`: Registro de formatadores built-in
+
+### Utilitários
+
+- `registry/`: File registry + paths
+- `reporting/`: Default reporter
+- `runtime/`: Node adapter
+- `schema/`: Schema versioning
+- `utils/`: chalk-safe, exec-safe, import-safe, type declarations
+
+## src/analysts/
+
+Sistema de análise multi-linguagem e multi-CI/CD.
+
+### Detectores Gerais (`detectors/`)
+
+12 detectores especializados:
+- **architecture**: Análise de estrutura arquitetural
+- **bugs-ml**: Detecção de bugs via ML (8 padrões, pontuação Bayesiana)
+- **code-fragile**: Código frágil e propenso a erros
+- **dependencies**: Análise de dependências
+- **duplications**: Detecção de duplicação
+- **monorepo**: Suporte a monorepos (pnpm-workspace, lerna, nx, turbo)
+- **performance**: Problemas de performance
+- **phantoms**: Arquivos fantasma (não importados)
+- **recommendation**: Recomendações de boas práticas
+- **security**: Problemas de segurança
+- **structure**: Problemas estruturais
+
+### Infraestrutura
+
+| Diretório | Função |
+|-----------|--------|
+| `registry/` | Registro central e autodiscovery |
+| `plugins/` | Plugin system (analyst-formatter, detector-documentation, detector-markdown, detector-node) |
+| `corrections/` | Quick-fixes, auto-fix, alias-imports, pruning, barrels, type-safety, map-reversion, scoring |
+| `converters/` | Conversão entre plataformas CI/CD |
+| `scorers/` | Engine de pontuação |
+| `strategists/` | Archetypes, suggestions contextuais, operator-structure |
+| `architects/` | Análise de estrutura de projetos, archetypes, diagnostic, signals |
+
+### Analisadores por Linguagem
+
+Cada um com estrutura `analysts/`, `detectors/`, `corrections/`, `scorers/`:
+
+| Linguagem | Parser | Implementação |
+|-----------|--------|---------------|
+| JavaScript/TypeScript | Babel (AST) | `js-ts/` |
+| React/JSX | Babel | `react/` |
+| CSS | postcss | `css/` + `css/plugins/` |
+| CSS-in-JS | postcss | `css-in-js/` + `plugins/` |
+| HTML | htmlparser2 | `html/` |
+| SVG | heuristic | `svg/` |
+| XML | fast-xml-parser | `xml/` |
+| Tailwind CSS | heuristic | `tailwind/` + `plugins/` |
+| Python | heuristic | `python/` |
+| Shell | heuristic | `shell/` |
+| SQL | heuristic | `sql/` |
+| Go | heuristic | `go/` |
+| Rust | heuristic | `rust/` |
+| PHP | heuristic | `php/` |
+
+### Analisadores de CI/CD
+
+Cada um com `analysts/`, `detectors/`, `corrections/`, `reports/`, `scorers/`:
+
+| Plataforma | Diretório |
+|------------|-----------|
+| GitHub Actions | `github-actions/` |
+| GitLab CI | `gitlab-ci/` |
+| CircleCI | `circleci/` |
+| Jenkins | `jenkins/` |
+| Azure Pipelines | `azure-pipelines/` |
+
+## src/guardian/
+
+Pipeline de integridade com assinatura GPG (Ed25519).
+
+| Arquivo | Função |
+|---------|--------|
+| `baseline.ts` | Gerenciamento de baselines (criação, carga, salvamento) |
+| `constants.ts` | Constantes do sistema |
+| `diff.ts` | Diferenças entre baseline e estado atual |
+| `gpg.ts` | Assinatura e verificação GPG |
+| `hash.ts` | Hashing de arquivos (xxhash) |
+| `integrity.ts` | Verificação de integridade central |
+| `records.ts` | Registros de auditoria |
+| `result.ts` | Tipos de resultado |
+| `sentinel.ts` | Monitoramento sentinel contínuo |
+| `snapshot.ts` | Snapshots de integridade |
+| `verifier.ts` | Verificador de integridade |
+| `watcher-hidden.ts` | Watcher oculto para detecção de alterações |
+
+## src/licenses/
+
+Gestão de licenças SPDX.
+
+| Arquivo | Função |
+|---------|--------|
+| `disclaimer.ts` | Adição/verificação de headers SPDX |
+| `fs-utils.ts` | Utilitários de filesystem |
+| `generate-notices.ts` | Geração de THIRD-PARTY-NOTICES.txt |
+| `header-options.ts` | Opções de headers SPDX |
+| `licenses.ts` | Scan de licenças em dependências |
+| `normalizer.ts` | Normalização de nomes de licenças |
+| `policy.ts` | Políticas de licença (checkLicenseStatus) |
+| `scanner.ts` | Scanner de dependências |
+| `types.ts` | Tipos do módulo |
+| `spdx.d.ts` | Declaração de tipos SPDX |
+
+## src/vulnerabilities/
+
+Scan de vulnerabilidades.
+
+| Arquivo | Função |
+|---------|--------|
+| `npm-audit.ts` | Integração com npm audit |
+| `scanner.ts` | Scanner genérico |
+| `vulnerabilities.ts` | Lógica principal de scan |
+
+## src/caretakers/
+
+Transformações automáticas no código fonte.
+
+| Arquivo | Função |
+|---------|--------|
+| `caretaker-imports.ts` | Gestão de aliases de import |
+| `imports.ts` | Lógica de imports |
+| `imports-barrel.ts` | Gerenciamento de barrels (index.ts) |
+| `map-reversion.ts` | Reversão de mapas de renomeação |
+| `pruning.ts` | Poda de arquivos órfãos |
+| `scoring.ts` | Pontuação de caretakers |
+
+## src/reports/
+
+Geração de relatórios.
+
+| Arquivo/Diretório | Função |
+|-------------------|--------|
+| `advisor.ts` | Conselheiro de diagnóstico |
+| `advisor-mahoraga.ts` | Conselheiro específico do mahoraga |
+| `analise-async-patterns.ts` | Análise de padrões assíncronos |
+| `async-analysis.ts` | Análise assíncrona |
+| `compliance.ts` | Relatórios de compliance |
+| `compliance/` | ISO 27001, SOC 2 mappers |
+| `filter-smart.ts` | Filtro inteligente de dados |
+| `fragmentation.ts` | Fragmentação de relatórios grandes |
+| `generator-report.ts` | Gerador de relatórios |
+| `processing.ts` | Processamento de relatórios |
+| `reader.ts` | Leitor de relatórios salvos |
+| `report-archetypes.ts` | Archetypes de relatórios |
+| `report-caretaker-health.ts` | Saúde do caretaker |
+| `report-patterns-usage.ts` | Padrões de uso |
+| `report-pruning.ts` | Relatório de poda |
+| `report-structure.ts` | Estrutura de relatórios |
+| `report-type-definitions.ts` | Tipos de relatórios |
+| `streaming.ts` | Streaming de dados |
+| `streaming-report.ts` | Streaming NDJSON |
+| `structure.ts` | Estrutura de relatórios |
+
+## src/shared/
+
+Utilitários compartilhados.
+
+| Diretório/Arquivo | Função |
+|-------------------|--------|
+| `context-project.ts` | Contexto do projeto |
+| `data-processing/` | Processamento de dados |
+| `formatters/` | Motores de formatação (core, engines, formatters) com suporte a supressão inline via `@mahoraga-disable` |
+| `helpers.ts` / `helpers/` | Helpers diversos |
+| `impar.ts` | Utilitário ímpar |
+| `imports.ts` | Imports compartilhados |
+| `marketplace/` | Marketplace de analistas |
+| `memory.ts` | Memória de conversação persistente |
+| `persistence.ts` / `persistence/` | Persistência de estado |
+| `plugins/` | Sistema de plugins |
+| `structure.ts` | Estrutura de dados |
+| `validation.ts` / `validation/` | Validação de dados |
+
+## src/types/
+
+Definições de tipos TypeScript. 14 namespaces:
+
+| Namespace | Conteúdo |
+|-----------|----------|
+| `analysts/` | Tipos de analisadores e correções |
+| `caretakers/` | Tipos de caretakers |
+| `common/` | Tipos comuns |
+| `core/` | Tipos do core (config, execution, messages, parsing) |
+| `guardian/` | Tipos do guardian |
+| `licenses/` | Tipos de licenças |
+| `processing/` | Tipos de processamento |
+| `project/` | Tipos de projeto |
+| `scripts/` | Tipos de scripts |
+| `sdk/` | Tipos do SDK |
+| `shared/` | Tipos compartilhados |
+| `structure/` | Tipos estruturais |
+| `vulnerabilities/` | Tipos de vulnerabilidades |
+
+## src/scripts/
+
+| Arquivo | Função |
+|---------|--------|
+| `migrar-aliases.ts` | Script de migração de aliases de import |
+
+## src/node.loader.ts
+
+Loader ESM customizado que resolve path aliases (`@core/`, `@cli/`, `@analysts/`, `@types/`, etc.) em tempo de execução. ~160+ mapeamentos.

package/Docs/02-componentes/configuracao.md

@@ -0,0 +1,110 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [componente]
+status: aceito
+created: 2026-07-25
+---
+
+# Configuração (`mahoraga.config.json`)
+
+## Fluxo de Carregamento
+
+```
+mahoraga.config.json
+       │
+       ▼
+  converterConfigSimplificada()
+       │  Transforma chaves amigáveis (ex: "exclude")
+       │  em chaves internas (ex: "INCLUDE_EXCLUDE_RULES")
+       ▼
+  mesclarProfundo(config, resultado)
+       │  Deep merge com precedência:
+       │  1. CLI flags / env vars
+       │  2. mahoraga.config.json
+       │  3. System defaults (configPadrao)
+       ▼
+  config global (acessível via import { config } from '@core/config')
+```
+
+## Comportamento de Merge
+
+O `mesclarProfundo` aplica regras diferentes por tipo:
+
+| Tipo | Comportamento | Exemplo |
+|------|--------------|---------|
+| Objeto plano | Merge recursivo | `languages`, `rules`, `detectorMarkdown`, `autoFix` |
+| Array (`exclude`) | **Aditivo**: mergeado com defaults do sistema | `["temp/**"]` adiciona aos defaults |
+| Primitivo | Substitui o valor default | `locale: "en"` |
+
+### Caso crítico: `exclude`
+
+Diferentemente de outros sistemas, o campo `exclude` no `mahoraga.config.json` é **aditivo**:
+
+```jsonc
+{
+  "exclude": ["temp/**", "logs/**"]
+}
+```
+
+O resultado final será: `[...defaultsDoSistema, "temp/**", "logs/**"]` — os defaults nunca são perdidos.
+
+Isso é implementado em `converterConfigSimplificada` (`src/core/config/config.ts`), que faz o merge com `configPadrao.INCLUDE_EXCLUDE_RULES.globalExcludeGlob` antes de armazenar.
+
+## Hierarquia de Precedência
+
+1. **CLI flags**: `--include`, `--exclude` (máxima prioridade)
+2. **Environment variables**: `MAHORAGA_*`
+3. **`mahoraga.config.json** (ou `src/config.json` como fallback)
+4. **System defaults** (`configPadrao` em `src/core/config/config.ts`)
+
+## Arquitetura
+
+### `src/core/config/config.ts`
+
+- `configPadrao` — objeto com todos os valores default do sistema
+- `config` — clone profundo de `configPadrao`, exportado como singleton
+- `converterConfigSimplificada(raw)` — transforma chaves do usuário para formato interno
+- `mesclarProfundo(target, src)` — merge recursivo com proteção prototype pollution
+- `inicializarConfigDinamica()` — carrega e mergeia config do arquivo + env + CLI
+
+### `src/core/config/excludes-padrao.ts`
+
+- `EXCLUDES_PADRAO` — categorias de exclusão por tipo de projeto
+- `getExcludesRecomendados(tipo)` — obtém defaults baseados no tipo de projeto detectado
+- `mesclarConfigExcludes(usuario, tipo)` — merge dos excludes do usuário com defaults
+- `isPadraoExclusaoSeguro(padrao)` — evita padrões perigosos como `**/*`
+
+## Componentes Relacionados
+
+- `src/core/config/include-exclude.ts` — avaliação de include/exclude via micromatch
+- `src/shared/helpers/suppressao.ts` — supressão inline via `@mahoraga-disable`
+- `src/shared/helpers/rule-config.ts` — configuração por regra (`rules.nome-da-regra.exclude`)
+
+## Exemplo Completo
+
+```jsonc
+{
+  "locale": "pt",
+  "languages": {
+    "typescript": true,
+    "javascript": true,
+    "shell": true
+  },
+  "exclude": ["temp/**"],
+  "suppress": {
+    "paths": ["**/tests/**"],
+    "severity": { "no-console": "warning" }
+  },
+  "rules": {
+    "ml-magic-numbers": {
+      "severity": "off"
+    }
+  },
+  "detectorMarkdown": {
+    "checkReferences": false,
+    "whitelist": {
+      "dirs": ["Docs"]
+    }
+  }
+}
+```

package/Docs/02-componentes/supressao-inline.md

@@ -0,0 +1,88 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [componente]
+status: aceito
+created: 2026-07-25
+---
+
+# Supressão Inline (`@mahoraga-disable`)
+
+## Propósito
+
+Permite que o usuário desabilite analistas e formatadores em linhas ou blocos específicos do código fonte, via comentários inline. Evita falsos positivos e protege trechos que não devem ser modificados.
+
+## Arquitetura
+
+```
+Código fonte com @mahoraga-disable
+         │
+         ▼
+  suppressao.ts::extrairSupressoes(src)
+         │
+         ▼
+  RegrasSuprimidas { porLinha: Map<line, Set<rule>>, blocosAtivos: Set<rule> }
+         │
+         ├──► Analysts: analyst-wrapper.ts::filtrarOcorrenciasSuprimidas()
+         │
+         └──► Formatter: commons.ts::extrairLinhasProtegidasFormatador(src)
+                           │
+                           ▼
+                     Set<number> (linhas protegidas)
+                           │
+                           ▼
+               collapseRepeatedPunct(code, protectedLines)
+               fixSpacingAroundPunct(code, protectedLines)
+               normalizeRelationalOperators(code, protectedLines)
+```
+
+## Componentes
+
+### `src/shared/helpers/suppressao.ts`
+
+Core do sistema. Parseia comentários `@mahoraga-disable` no código e retorna `RegrasSuprimidas`.
+
+**Exporta:**
+- `extrairSupressoes(src)` — analisa o código e retorna as supressões
+- `isRegraSuprimida(regra, linha, supressoes)` — verifica se uma regra está suprimida em uma linha
+- `filtrarOcorrenciasSuprimidas(ocorrencias, analista, src)` — filtra ocorrências suprimidas
+
+### `src/shared/formatters/formatters/commons.ts`
+
+Integração com o formatador mínimo.
+
+**Exporta:**
+- `extrairLinhasProtegidasFormatador(src)` — converte supressões em `Set<number>` de linhas protegidas para o formatador
+- `corrigirPontuacaoECodigo(code, protectedLines?)` — função principal com suporte a proteção
+- `corrigirPontuacaoECodigoConservador(code, protectedLines?)` — versão conservadora
+
+### `src/analysts/plugins/analyst-formatter.ts`
+
+Integração com o analista de formatação.
+
+- `extrairLinhasProtegidas(src)` — bridge que alimenta `formatarMarkdownMinimo()` com linhas protegidas
+
+## Regras do Formatador
+
+| Regra | Efeito |
+|-------|--------|
+| `pontuacao-repetida` | Impede colapso de `;;`, ` ...`, `,,  etc |
+| `espacamento-incorreto` | Impede correção de espaços ao redor de pontuação |
+| `formatador` | Desativa todas as correções |
+| `analista-formatador` | Desativa apenas o analista de verificação |
+| `*` | Desativa todos os sistemas |
+
+## Exemplos
+
+```typescript
+// @mahoraga-disable-next-line pontuacao-repetida
+const x = a;;  // ;; preservado
+
+// @mahoraga-disable formatador
+url = "https://example.com/path";
+// @mahoraga-enable formatador
+```
+
+## Testes
+
+- `tests/shared/helpers/suppressao.test.ts` — testes do parser de supressão
+- `tests/shared/formatters/formatters/commons.test.ts` — testes do formatador

package/Docs/03-guias/_index.md

@@ -0,0 +1,173 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [moc, guias]
+created: 2026-07-24
+updated: 2026-07-25
+---
+
+# Guias
+
+## Desenvolvimento
+
+- [[contribuindo|Contribuindo]]: Como contribuir com o projeto
+- [[testes|Testes]]: Padrões e boas práticas de teste
+
+## Guia Rápido de Comandos
+
+### Diagnóstico
+
+```bash
+mahoraga diagnosticar                    # análise padrão
+mahoraga diagnosticar --full             # completa (todos os detectores)
+mahoraga diagnosticar --fast             # rápida (apenas detectores essenciais)
+mahoraga diagnosticar --compact          # saída compacta
+mahoraga diagnosticar --json             # saída JSON
+mahoraga diagnosticar --detalhado        # saída detalhada
+mahoraga diagnosticar --executive        # relatório executivo (1 página)
+mahoraga diagnosticar --monorepo         # modo monorepo
+mahoraga diagnosticar --stream           # streaming NDJSON
+mahoraga diagnosticar --guardian-check   # verificar Guardian junto
+mahoraga diagnosticar --auto-fix         # corrigir automaticamente
+mahoraga diagnosticar --include "src/**" --exclude "**/*.test.ts"
+```
+
+### Guardian (Integridade)
+
+```bash
+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
+mahoraga guardian --json                 # saída JSON
+```
+
+### Licenças
+
+```bash
+mahoraga licencas scan                   # scan de dependências
+mahoraga licencas notices generate       # gerar THIRD-PARTY-NOTICES
+mahoraga licencas disclaimer add         # adicionar headers SPDX
+mahoraga licencas disclaimer verify      # verificar headers SPDX
+```
+
+### Compliance
+
+```bash
+mahoraga compliance report iso-27001     # relatório ISO 27001
+mahoraga compliance report soc2          # relatório SOC 2
+mahoraga compliance report soc2 --json   # em JSON
+```
+
+### Análise CI/CD
+
+```bash
+mahoraga github-actions scan             # GitHub Actions
+mahoraga github-actions gate             # quality gate
+mahoraga gitlab-ci scan                  # GitLab CI
+mahoraga circleci scan                   # CircleCI
+mahoraga jenkins scan                    # Jenkins
+mahoraga azure scan                      # Azure Pipelines
+mahoraga convert --from github --to gitlab  # converter templates
+```
+
+### Vulnerabilidades
+
+```bash
+mahoraga vulnerabilidades scan           # scan npm audit
+mahoraga vulnerabilidades scan --json    # saída JSON
+```
+
+### Manutenção de Código
+
+```bash
+mahoraga formatar --write                # formatar código
+mahoraga formatar --check                # verificar apenas
+mahoraga fix-types --target src          # corrigir any/unknown
+mahoraga fix-types --dry-run             # simular correção
+mahoraga fix-types --interactive         # modo interativo
+mahoraga podar                           # remover arquivos órfãos
+mahoraga names --scan                    # extrair nomes de variáveis
+mahoraga names --apply                   # aplicar renomeações
+mahoraga imports --scan                  # escanear aliases
+mahoraga imports --apply                 # aplicar correções de import
+mahoraga barrels --scan                  # preview de barrels
+mahoraga barrels --generate              # gerar barrels
+```
+
+### Plugins e Marketplace
+
+```bash
+mahoraga plugins list                    # listar plugins instalados
+mahoraga plugins install <pacote>        # instalar plugin
+mahoraga plugins remove <pacote>         # remover plugin
+mahoraga marketplace search <termo>      # buscar analistas
+mahoraga marketplace install <nome>      # instalar do marketplace
+```
+
+### Performance e Métricas
+
+```bash
+mahoraga perf snapshot                   # criar snapshot
+mahoraga perf baseline                   # definir baseline
+mahoraga perf compare                    # comparar snapshots
+mahoraga metricas                        # métricas de execução
+mahoraga metricas --analistas            # métricas por analista
+mahoraga metricas --json                 # JSON output
+
+mahoraga analistas                       # listar analistas
+mahoraga analistas --json                # listar em JSON
+mahoraga analistas --plugins             # listar plugins
+```
+
+### Utilitários
+
+```bash
+mahoraga otimizar-svg --write            # otimizar SVGs
+mahoraga reverter listar                 # listar reversões
+mahoraga reverter move <id>              # reverter movimento
+mahoraga atualizar --global              # auto-update
+mahoraga atualizar --local               # update local
+mahoraga formatters list                 # listar formatadores
+```
+
+## Convenções de Código
+
+- **Nomenclatura:** Em português (BR) para funções e variáveis
+- **Idioma:** Português é o idioma padrão do projeto
+- **i18n:** Mensagens de usuário sempre em pt, en, zh, ja
+- **Componentes:** Functional components com default export
+- **Imports:** Path aliases (`@core/`, `@cli/`, etc.): nunca caminhos relativos profundos
+- **Testes:** Vitest com `vi.hoisted()` + `vi.mock()`
+
+## Como Criar um Novo Comando CLI
+
+1. Criar arquivo em `src/cli/commands/command-meu-comando.ts`
+2. Implementar função que recebe `aplicarFlagsGlobais` e retorna um `Command` do Commander
+3. Adicionar o comando em `src/cli/commands/commands.ts`
+4. Adicionar mensagens i18n em todas as 4 línguas
+5. Criar testes em `tests/cli/commands/command-meu-comando.test.ts`
+6. Usar `vi.hoisted()` para mocks, `parseAsync([], { from: 'user' })` para execução
+
+## Testes
+
+```bash
+# Suite completa
+npm test
+
+# Testes específicos
+npx vitest run tests/cli/commands/command-format.test.ts
+
+# Coverage
+npm run coverage
+
+# Modo watch
+npx vitest
+```
+
+## Build
+
+```bash
+npm run build          # compilar TypeScript
+npm run typecheck      # verificar tipos (sem emitir)
+npm run lint           # ESLint
+```