@mocoto/mahoraga 0.14.9 → 0.15.1

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
+```

package/docs/03-guias/contribuindo.md

@@ -0,0 +1,71 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [guia]
+status: rascunho
+created: 2026-07-24
+updated: 2026-07-25
+---
+
+# Contribuindo
+
+## Workflow
+
+1. Crie uma branch: `tipo/descricao-curta` (ex: `feat/novo-comando`)
+2. Faça commits atômicos seguindo [conventional commits](https://www.conventionalcommits.org/)
+3. Abra um Pull Request com descrição do *porquê*, não apenas do *que*
+4. PRs devem ser pequenos (máx 200-400 linhas)
+
+## Checklist pré-PR
+
+- [ ] `npm run typecheck` passando
+- [ ] `npm test` passando
+- [ ] `npm run build` passando
+- [ ] Cobertura adequada nos arquivos alterados
+- [ ] Mensagens i18n atualizadas em pt, en, zh, ja
+- [ ] Documentação atualizada em `Docs/`
+
+## Convenções
+
+- Commits: `tipo(escopo): descrição no imperativo`
+- Tipos: feat, fix, refactor, docs, test, chore
+- Branches: `tipo/issue-123-descricao`
+- NUNCA force push
+- NUNCA use `git add.`: adicione apenas arquivos intencionais
+- Revise `git diff --cached` por segredos antes de commitar
+
+## Estrutura de um Comando
+
+```typescript
+// src/cli/commands/command-exemplo.ts
+import { Command } from 'commander';
+
+export function comandoExemplo(aplicarFlagsGlobais: (opts: unknown) => void): Command {
+  const cmd = new Command('exemplo').alias('ex')
+    .description('Faz algo incrível')
+    .option('-t, --target <path>', 'Diretório alvo');
+
+  cmd.action(async (opts) => {
+    aplicarFlagsGlobais(opts);
+    // implementação...
+  });
+
+  return cmd;
+}
+```
+
+## Convenções de i18n
+
+Toda mensagem visível ao usuário deve ser adicionada em 4 línguas:
+
+- `src/core/messages/pt/ ...`: Português (padrão)
+- `src/core/messages/en/ ...`: Inglês
+- `src/core/messages/zh/ ...`: Chinês
+- `src/core/messages/ja/ ...`: Japonês
+
+Mensagens são objetos `as const` exportados e tipados.
+
+## Dependências
+
+- **Runtime:** Node.js >=24.16.0
+- **Gerenciador:** npm
+- **Nunca adicione** `@types/*` como dependência de produção: use `devDependencies`

package/docs/03-guias/testes.md

@@ -0,0 +1,133 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [guia, testes]
+status: rascunho
+created: 2026-07-24
+updated: 2026-07-25
+---
+
+# Testes
+
+## Stack
+
+- **Framework:** Vitest v4
+- **Coverage:** v8 (via `@vitest/coverage-v8`)
+- **Mocks:** `vi.hoisted()` + `vi.mock()` no topo dos arquivos
+- **Organização:** `tests/` espelha `src/` em estrutura de diretórios
+- **Aliases:** Mesma configuração de paths do tsconfig (definidos em `vitest.config.ts`)
+
+## Padrões
+
+### Teste de Comando CLI
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockLog = vi.hoisted(() => ({ info: vi.fn(), erro: vi.fn() }));
+
+vi.mock('@core/messages', () => ({
+  getMessages: () => ({ log: mockLog, /* ... */ }),
+}));
+
+import { comandoFormatar } from '../../../src/cli/commands/command-format.js';
+
+describe('comandoFormatar', () => {
+  beforeEach(() => { vi.clearAllMocks(); });
+
+  it('cria comando com nome esperado', () => {
+    const cmd = comandoFormatar(vi.fn());
+    expect(cmd.name()).toBe('formatar');
+  });
+
+  it('captura erros no scanRepository', async () => {
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+    const scanRepo = (await import('@core/execution')).scanRepository as ReturnType<typeof vi.fn>;
+    scanRepo.mockRejectedValue(new Error('erro'));
+    const cmd = comandoFormatar(vi.fn());
+    await cmd.parseAsync([], { from: 'user' });
+    expect(mockLog.erro).toHaveBeenCalled();
+    exitSpy.mockRestore();
+  });
+});
+```
+
+### Teste com Callback Pattern (Mocks Complexos)
+
+```typescript
+// Para módulos com mocking complexo (ex: createRequire, promisify):
+const mockFn = vi.hoisted(() => vi.fn().mockResolvedValue([]));
+
+vi.mock('node:module', () => ({
+  createRequire: () => (id: string) => {
+    if (id === 'license-checker') return { init: mockFn };
+    return require(id);
+  },
+}));
+
+vi.mock('node:util', () => ({ promisify: () => (fn: any) => fn }));
+
+// Import dinâmico após os mocks
+const mod = await import('../../src/licenses/generate-notices.js');
+```
+
+### Teste de Módulo com FS
+
+```typescript
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mahoraga-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+```
+
+### Teste de Tipos
+
+```typescript
+import { describe, it, expectTypeOf } from 'vitest';
+import type { MeuTipo } from '../../src/types/index.js';
+
+describe('MeuTipo', () => {
+  it('deve ser string', () => {
+    expectTypeOf<MeuTipo>().toBeString();
+  });
+});
+```
+
+## Cobertura
+
+```bash
+npm run coverage                    # relatório completo
+npx vitest run --coverage --reporter=text  # apenas terminal
+npx vitest run --coverage --reporter=html   # HTML interativo
+```
+
+### Alvo
+
+- Cobertura geral target: 56%+ statements
+- Novos arquivos: 80%+ statements
+- Módulos críticos (licenses, vulnerabilities, guardian): 90%+
+
+## Dicas Avançadas
+
+- `parseAsync([], { from: 'user' })`: Commander v15 não aceita args posicionais
+- `vi.spyOn(process, 'exit')`: sempre restaurar com `.mockRestore()` no afterEach
+- `vi.hoisted()` para variáveis que precisam existir antes dos mocks serem avaliados
+- Testes de FS real usar `os.tmpdir()` + limpeza em `afterEach`
+- Mocks de `@core/messages` são os mais comuns: criar helper se repetir muito
+- Para testar barrels (index.ts), importar o barrel e verificar se as exportações existem
+
+## Debug
+
+```bash
+npx vitest --reporter=verbose        # log detalhado
+npx vitest --reporter=json           # saída JSON
+npx vitest run tests/meu-teste.test.ts --reporter=verbose
+```

package/docs/04-glossario/_index.md

@@ -0,0 +1,29 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [moc, glossario]
+created: 2026-07-24
+---
+
+# Glossário
+
+## Termos do Domínio
+
+| Termo | Definição |
+|-------|-----------|
+| **Analyst** | Analisador especializado que processa um aspecto do código (AST, dependências, etc.) |
+| **Caretaker** | Módulo que aplica transformações automáticas no código fonte |
+| **Guardian** | Pipeline de integridade que verifica baseline vs estado atual |
+| **Baseline** | Estado de referência do projeto usado pelo Guardian |
+| **Registry** | Registro central de analysts com descoberta automática |
+| **Runtime** | Adaptador de ambiente (Node, Deno, Bun) |
+| **MOC** | Map of Content: nota índice que linka notas relacionadas |
+| **ADR** | Architecture Decision Record: registro de decisão arquitetural |
+| **MCP** | Model Context Protocol: protocolo para agentes de IA acessarem ferramentas |
+
+## Tags Utilizadas
+
+- `#moc`: Nota do tipo Mapa de Conteúdo
+- `#adr`: Architecture Decision Record
+- `#guia`: Guia de desenvolvimento
+- `#glossario`: Entrada de glossário
+- `#termo`: Definição de termo

package/docs/04-glossario/termos.md

@@ -0,0 +1,247 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [glossario, termo]
+created: 2026-07-24
+updated: 2026-07-25
+---
+
+# Termos do Domínio
+
+## A
+
+### ADR (Architecture Decision Record)
+
+Registro de decisão arquitetural. Documenta o contexto, a decisão tomada, consequências e alternativas consideradas. Usa o template em `templates/ADR.md`.
+
+### Advisor
+
+Módulo que fornece recomendações contextuais baseadas nos resultados da análise. Dois tipos: genérico (`advisor.ts`) e específico do mahoraga (`advisor-mahoraga.ts`).
+
+### Analyst
+
+Analisador especializado que processa um aspecto específico do código. Descobertos automaticamente pelo Registry. Exemplos: analisador de AST, analisador de dependências, analisador de métricas.
+
+### Archetype
+
+Padrão arquitetural detectado pelo sistema de análise. Usado para classificar projetos e sugerir boas práticas específicas.
+
+### Autodiscovery
+
+Mecanismo que descobre automaticamente analistas e detectores sem registro manual. Implementado em `src/analysts/registry/autodiscovery.ts`.
+
+### Azure Pipelines
+
+Plataforma de CI/CD da Microsoft. O Mahoraga analisa pipelines Azure com detectores e correções específicos.
+
+## B
+
+### Babel
+
+Parser de JavaScript/TypeScript usado pelo Mahoraga para análise de AST (Árvore Sintática Abstrata).
+
+### Barrel
+
+Arquivo `index.ts` que re-exporta módulos de um diretório. O Mahoraga pode escanear, gerar e gerenciar barrels automaticamente.
+
+### Baseline
+
+Estado de referência do projeto usado pelo Guardian para detectar alterações não autorizadas. Armazenado em `.mahoraga/baseline/`.
+
+## C
+
+### Caretaker
+
+Módulo que aplica transformações automáticas no código fonte. Exemplo: `caretaker-imports.ts` gerencia aliases de import.
+
+### CircleCI
+
+Plataforma de CI/CD. O Mahoraga analisa pipelines CircleCI com detectores e correções.
+
+### CLI
+
+Command Line Interface. Interface de linha de comando implementada com Commander.js.
+
+### Compliance
+
+Conformidade com standards de segurança e governança. O Mahoraga gera relatórios ISO 27001 e SOC 2.
+
+### Conventional Commits
+
+Padrão de mensagens de commit: `tipo(escopo): descrição`. Tipos usados: feat, fix, refactor, docs, test, chore.
+
+### Converter
+
+Módulo que converte pipelines entre plataformas de CI/CD (ex: GitHub Actions → GitLab CI).
+
+## D
+
+### Detector
+
+Unidade mínima de análise que verifica um aspecto específico do código. Múltiplos detectores compõem um analyst.
+
+### Disclaimer
+
+Header SPDX adicionado ao topo de arquivos fonte para declaração de licença. O módulo `licenses/disclaimer.ts` gerencia isso.
+
+## E
+
+### Ed25519
+
+Algoritmo de curva elíptica usado pelo Guardian para assinatura GPG. Escolhido por segurança e performance.
+
+## F
+
+### Fix Types
+
+Subcomando que corrige automaticamente tipos inseguros (`any` → tipos concretos, `unknown` → tipos específicos).
+
+## G
+
+### GitHub Actions
+
+Plataforma de CI/CD do GitHub. O Mahoraga analisa workflows YAML com detectores especializados.
+
+### GitLab CI
+
+Plataforma de CI/CD do GitLab. Análise de pipelines `.gitlab-ci.yml`.
+
+### GPG (GNU Privacy Guard)
+
+Sistema de criptografia usado pelo Guardian para assinar e verificar baselines de integridade.
+
+### Guardian
+
+Pipeline de integridade que compara o baseline com o estado atual do projeto, detectando desvios e alterações suspeitas. Usa assinatura GPG Ed25519.
+
+## I
+
+### i18n
+
+Internacionalização. O Mahoraga suporta 4 idiomas: Português (padrão), Inglês, Chinês, Japonês.
+
+### Inquisitor
+
+Módulo do core que coordena a execução dos analisadores durante o scan.
+
+## J
+
+### Jenkins
+
+Plataforma de CI/CD open-source. O Mahoraga analisa pipelines Jenkins.
+
+## L
+
+### Loader ESM
+
+Mecanismo em `src/node.loader.ts` que resolve path aliases em tempo de execução, permitindo imports como `@core/execution`.
+
+## M
+
+### MCP (Model Context Protocol)
+
+Protocolo padrão que permite agentes de IA acessarem ferramentas e recursos externos de forma segura.
+
+### Marketplace
+
+Sistema de distribuição de analistas comunitários. Comandos: `marketplace search`, `marketplace install`.
+
+### MOC (Map of Content)
+
+Nota índice que funciona como hub de navegação, linkando notas relacionadas sobre um mesmo tema. Substitui pastas profundas na documentação.
+
+### Monorepo
+
+Repositório com múltiplos projetos. O Mahoraga detecta configurações pnpm-workspace, lerna, nx e turbo.
+
+## N
+
+### NDJSON (Newline Delimited JSON)
+
+Formato de streaming usado para projetos grandes. Cada linha é um JSON válido, permitindo processamento incremental.
+
+### npm audit
+
+Ferramenta do npm para scan de vulnerabilidades em dependências. Integrada ao módulo `vulnerabilities/`.
+
+## P
+
+### Phantom
+
+Arquivo que existe no filesystem mas não é importado por nenhum outro módulo. Detectado pelo detector de phantoms.
+
+### Plugin
+
+Extensão do sistema de análise. Plugins built-in: analyst-formatter, detector-documentation, detector-markdown, detector-node.
+
+### Poda (Pruning)
+
+Remoção automatizada de arquivos órfãos e código morto. Comando: `mahoraga podar`.
+
+### postcss
+
+Parser de CSS usado pelos analisadores CSS e CSS-in-JS.
+
+## R
+
+### Registry
+
+Registro central de analysts com descoberta automática via `autodiscovery.ts`. Permite que novos analysts sejam detectados sem registro manual.
+
+### Runtime
+
+Camada de abstração do ambiente de execução. Suporta Node.js através do adaptador em `src/core/runtime/`.
+
+## S
+
+### Scanner
+
+Motor que percorre o filesystem, identifica arquivos por tipo e coordena a análise. Presente em `core/execution/` e `licenses/scanner.ts`.
+
+### Schema Versioning
+
+Sistema de versionamento de schemas de relatórios para compatibilidade retroativa.
+
+### Sentinel
+
+Mecanismo do Guardian que monitora continuamente alterações no projeto.
+
+### SOC 2
+
+Standard de auditoria de controles organizacionais. Relatório gerado pelo módulo `reports/compliance/`.
+
+### SPDX
+
+Software Package Data Exchange. Padrão para comunicação de informações de licenças. Usado pelo módulo `licenses/`.
+
+### Streaming
+
+Modo de saída NDJSON para projetos grandes, permitindo processamento incremental sem carregar tudo em memória.
+
+## T
+
+### THIRD-PARTY-NOTICES
+
+Arquivo gerado pelo Mahoraga listando todas as licenças de dependências do projeto.
+
+## W
+
+### Worker Pool
+
+Sistema de processamento paralelo em `src/core/workers/`. Gerencia fila de tarefas, workers e resultados.
+
+## X
+
+### xxhash
+
+Algoritmo de hashing não-criptográfico usado pelo Guardian para hash rápido de arquivos.
+
+## Índice de Tags
+
+| Tag | Uso |
+|-----|-----|
+| `#moc` | Nota Mapa de Conteúdo |
+| `#adr` | Architecture Decision Record |
+| `#guia` | Guia de desenvolvimento |
+| `#glossario` | Entrada de glossário |
+| `#termo` | Definição de termo individual |
+| `#componente` | Documentação de componente |