@mocoto/mahoraga 0.14.9 → 0.15.1

package/docs/01-arquitetura/_index.md

@@ -0,0 +1,152 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [moc, arquitetura]
+created: 2026-07-24
+updated: 2026-07-25
+---
+
+# Arquitetura
+
+## Visão Geral
+
+O Mahoraga é organizado em 6 camadas:
+
+### 1. Entry Point (`src/bin/index.ts`)
+
+Binário executável (`#!/usr/bin/env node`). Inicializa o loader ESM customizado (aliases em runtime), configura handlers globais de erro, carrega configuração, versão, memória de conversação, registra todos os comandos via `registrarComandos()` e executa `program.parseAsync()`.
+
+### 2. CLI Layer (`src/cli/`)
+
+Interface com o usuário via Commander.js. 27 comandos registrados em `commands.ts`, cada um implementado em um arquivo `command-*.ts`. Subcomandos para diagnóstico, guardian, CI/CD, licenças, compliance, manutenção, plugins.
+
+### 3. Core Layer (`src/core/`)
+
+Motor central do sistema:
+- **execution/**: Scanner, registry, workers, cache, ambiente, linguagens, schema
+- **config/**: Configuração default, scoring, paths, segurança, filtros
+- **parsing/**: Parsers baseados em Babel (AST) + parsers por linguagem
+- **messages/**: Sistema de i18n com suporte a pt (padrão), en, zh, ja
+- **workers/**: Worker pool para processamento paralelo
+- **corrections/**: Auto-fix engine
+
+### 4. Analysis Layer (`src/analysts/`)
+
+Analisadores especializados organizados por domínio:
+
+**Detectores gerais** (aplicáveis a qualquer projeto):
+- `detectors/`: 12 detectores: architecture, bugs-ml, code-fragile, dependencies, duplications, monorepo, performance, phantoms, recommendation, security, structure
+
+**Analisadores por linguagem** (cada um com analysts/, detectors/, corrections/, scorers/):
+- `js-ts/`, `react/`, `css/`, `css-in-js/`, `html/`, `svg/`, `xml/`, `tailwind/`, `python/`, `shell/`, `sql/`, `go/`, `rust/`, `php/`
+
+**Analisadores de CI/CD** (cada um com analysts/, detectors/, corrections/, reports/, scorers/):
+- `github-actions/`, `gitlab-ci/`, `circleci/`, `jenkins/`, `azure-pipelines/`
+
+**Infraestrutura:**
+- `registry/`: Autodiscovery de analistas
+- `plugins/`: Sistema de plugins (analyst-formatter, detector-documentation, detector-markdown, detector-node)
+- `corrections/`: Correções automáticas (quick-fixes, auto-fix, alias-imports, pruning, barrels, type-safety)
+- `converters/`: Conversão entre plataformas CI/CD
+- `scorers/`: Engine de pontuação
+- `strategists/`: Estratégias de análise (archetypes, suggestions)
+
+### 5. Service Layer
+
+| Módulo | Descrição |
+|--------|-----------|
+| `guardian/` | Pipeline de integridade com GPG (Ed25519). Baseline, snapshot, diff, sentinel, verifier |
+| `licenses/` | Gerenciamento de licenças SPDX. Scanner, normalizer, policy, disclaimer, notice generator |
+| `vulnerabilities/` | Scan de vulnerabilidades via npm audit |
+| `caretakers/` | Transformações automáticas: imports, barrels, pruning, map-reversion, scoring |
+| `reports/` | Relatórios: compliance (ISO 27001, SOC 2), advisor, archetypes, streaming NDJSON, fragments |
+
+### 6. Shared Layer (`src/shared/`)
+
+Utilitários compartilhados entre módulos:
+- `formatters/`: Motores de formatação (core, engines, formatters)
+- `persistence/`: Persistência de estado
+- `validation/`: Validação de dados
+- `marketplace/`: Marketplace de analistas
+- `plugins/`: Sistema de plugins
+- `helpers/`: Helpers diversos
+
+### 7. Types (`src/types/`)
+
+14 namespaces de tipos TypeScript: analysts, caretakers, common, core, guardian, licenses, processing, project, scripts, sdk, shared, structure, vulnerabilities.
+
+## Fluxo de Dados
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant CLI as src/cli/
+    participant CORE as src/core/
+    participant REG as Registry
+    participant ANALYST as Analysts
+    participant SVC as Services
+
+    User->>CLI: mahoraga diagnosticar
+    CLI->>CORE: scanRepository()
+    CORE->>REG: autodiscover()
+    REG-->>CORE: analysts[]
+    CORE->>ANALYST: analyze(project)
+    ANALYST-->>CORE: results[]
+    CORE->>SVC: compliance/generate
+    SVC-->>CORE: report
+    CORE-->>CLI: aggregated results
+    CLI-->>User: formatted output
+```
+
+## Alias System
+
+O projeto usa path aliases estilo `@pasta/arquivo` para todos os imports internos, resolvidos em três níveis:
+
+1. **tsconfig.json**: paths mapping (~160+ entradas)
+2. **node.loader.ts**: Loader ESM customizado para runtime
+3. **vitest.config.ts**: Aliases para ambiente de teste
+
+## Decisões Arquiteturais
+
+- [[ADR-001-estrutura-testes|ADR-001: Estrutura de Testes com Vitest]]
+- Novos ADRs devem seguir o template em `templates/ADR.md`
+
+## Diagrama de Componentes
+
+```mermaid
+flowchart LR
+    subgraph CLI["CLI Layer"]
+        CMD[commands.ts]
+        GHA[github-actions]
+        DIAG[diagnosticar]
+        LIC[licencas]
+    end
+    subgraph CORE["Core"]
+        EXEC[execution]
+        CONF[config]
+        MSG[messages]
+        WRK[workers]
+    end
+    subgraph ANAL["Analysts"]
+        LANG[js-ts/react/css/...]
+        CICD[gha/gitlab/circle/...]
+        DET[detectores]
+        CORR[corrections]
+    end
+    subgraph SVC["Services"]
+        GRD[guardian]
+        CAR[caretakers]
+        RPT[reports]
+    end
+    CLI --> CORE
+    CORE --> ANAL
+    CORE --> SVC
+```
+
+## Temas Arquiteturais
+
+- **Modularidade**: Cada módulo tem barrel (`index.ts`) e tipos próprios
+- **Autodiscovery**: Novos analistas são detectados sem registro manual
+- **i18n first**: Mensagens em pt, en, zh, ja desde o design
+- **Plugin system**: Analistas e detectores podem ser estendidos via plugins
+- **Streaming**: NDJSON para projetos grandes (>10k arquivos)
+- **Worker pool**: Processamento paralelo para análise intensiva

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/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