@mocoto/mahoraga 0.15.0 → 0.15.2

package/Docs/_home.md

@@ -0,0 +1,140 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [moc, index]
+created: 2026-07-24
+updated: 2026-07-25
+---
+
+# @mocoto/mahoraga: Documentação Viva
+
+CLI modular para análise, diagnóstico e manutenção de projetos JavaScript/TypeScript e multi-stack leve.
+
+## Navegação
+
+| Área                               | Descrição          |
+| ---------------------------------- | ------------------ | ------------------------------------------------------------ |
+| [[01-arquitetura/_index\           | Arquitetura]]      | Decisões arquiteturais, ADRs, diagramas, fluxos              |
+| [[02-componentes/_index\           | Componentes]]      | Documentação de todos os módulos do sistema                  |
+| [[02-componentes/supressao-inline\ | Supressão Inline]] | Sistema de `@mahoraga-disable` para analistas e formatadores |
+| [[03-guias/_index\                 | Guias]]            | Guias de contribuição, testes, CLI, debug                    |
+| [[04-glossario/_index\             | Glossário]]        | Termos do domínio e conceitos                                |
+| [[05-referencias/_index\           | Referências]]      | Links externos, specs, recursos                              |
+
+## Visão Geral
+
+Mahoraga é uma ferramenta CLI que funciona como "médico de projetos": analisa código fonte, detecta problemas de qualidade, segurança e arquitetura, e oferece correções automatizadas. Suporta múltiplas linguagens (JS, TS, React, CSS, HTML, Python, Shell, SQL, Go, Rust, PHP) e plataformas de CI/CD (GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure Pipelines).
+
+## Stack
+
+- **Runtime:** Node.js >=24.16.0
+- **Linguagem:** TypeScript (ES2024, NodeNext)
+- **Build:** tsc + tsc-alias
+- **Testes:** Vitest v4 + v8 coverage
+- **CLI:** Commander.js
+- **Parser:** Babel (AST), postcss, htmlparser2, fast-xml-parser
+- **GPG:** openpgp (Ed25519)
+- **i18n:** pt, en, zh, ja
+- **Licença:** MIT-0
+
+## Snapshot do Projeto
+
+| Métrica | Valor |
+|---------|-------|
+| Versão | 0.15.1 |
+| Comandos CLI | 27 |
+| Arquivos de teste | ~240 |
+| Testes | ~3300 |
+| Cobertura (statements) | ~48% |
+| Source lines | ~31k |
+| Diretórios em `src/` | 15+ |
+| Analisadores de linguagem | 11 |
+| Analisadores de CI/CD | 5 |
+| Línguas suportadas | 4 (pt, en, zh, ja) |
+
+## Arquitetura em Camadas
+
+```mermaid
+flowchart TB
+    subgraph Entry
+        bin["src/bin/index.ts<br/>Entry Point"]
+    end
+    subgraph CLI["CLI Layer<br/>src/cli/"]
+        CMDS["27 comandos<br/>Commander.js"]
+        DIAG["Diagnóstico"]
+        HELP["Helpers"]
+    end
+    subgraph CORE["Core Layer<br/>src/core/"]
+        EXEC["Execução<br/>Scanner / Workers"]
+        CONF["Config"]
+        PARSE["Parsing<br/>Babel + langs"]
+        I18N["i18n<br/>pt/en/zh/ja"]
+        CORR["Correções"]
+    end
+    subgraph ANALYSTS["Analysis Layer<br/>src/analysts/"]
+        DETECT["Detectores<br/>15+ especializados"]
+        LANG["Analisadores<br/>11 linguagens"]
+        CICD["Analisadores<br/>5 plataformas CI/CD"]
+        PLUGINS["Plugins"]
+    end
+    subgraph SERVICES["Service Layer"]
+        GUARDIAN["Guardian<br/>Integridade GPG"]
+        LICENSES["Licenças<br/>SPDX + scanner"]
+        VULN["Vulnerabilidades<br/>npm audit"]
+        CARETAKERS["Caretakers<br/>Transformações"]
+        REPORTS["Relatórios<br/>Compliance + Advisor"]
+    end
+    subgraph SHARED["Shared Layer<br/>src/shared/"]
+        FORM["Formatters"]
+        PERSIST["Persistência"]
+        VAL["Validação"]
+        MP["Marketplace"]
+    end
+    subgraph TYPES["Types<br/>src/types/"]
+        TINDEX["14 namespaces"]
+    end
+
+    bin --> CLI
+    CLI --> CORE
+    CORE --> ANALYSTS
+    CORE --> SERVICES
+    SERVICES --> SHARED
+    ANALYSTS --> SHARED
+    CORE --> TYPES
+    ANALYSTS --> TYPES
+    SERVICES --> TYPES
+```
+
+## Comandos Rápidos
+
+```bash
+# Diagnóstico
+mahoraga diagnosticar                    # análise padrão
+mahoraga diagnosticar --full             # completa
+mahoraga diagnosticar --fast             # rápida
+mahoraga diagnosticar --json             # JSON output
+
+# Integridade
+mahoraga guardian                        # verificar integridade
+mahoraga guardian --accept-baseline      # aceitar baseline
+
+# CI/CD
+mahoraga github-actions scan
+mahoraga gitlab-ci scan
+mahoraga circleci scan
+mahoraga convert --from github --to gitlab
+
+# Licenças
+mahoraga licencas scan
+mahoraga licencas notices generate
+mahoraga licencas disclaimer add
+
+# Manutenção
+mahoraga formatar --write
+mahoraga podar
+mahoraga fix-types --target src
+mahoraga imports --scan
+
+# Compliance
+mahoraga compliance report iso-27001
+mahoraga compliance report soc2
+```

package/Docs/partials/AVISO-PROVENIENCIA.md

@@ -0,0 +1,3 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+---

package/Docs/templates/ADR.md

@@ -0,0 +1,24 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [adr]
+status: proposto | aceito | deprecated
+created: {{date}}
+---
+
+# ADR-NNN: Título da Decisão
+
+## Contexto
+
+<!-- Por que essa decisão foi necessária? Qual problema resolve? -->
+
+## Decisão
+
+<!-- O que foi decidido? Qual caminho foi escolhido? -->
+
+## Consequências
+
+<!-- Impactos positivos e negativos da decisão -->
+
+## Alternativas Consideradas
+
+<!-- Quais outras opções foram avaliadas e por que foram descartadas? -->

package/Docs/templates/componente.md

@@ -0,0 +1,34 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [componente]
+status: rascunho
+created: {{date}}
+---
+
+# Nome do Componente
+
+## Propósito
+
+<!-- O que este componente faz? Qual problema resolve? -->
+
+## Dependências
+
+- Entrada: <!-- o que ele recebe -->
+- Saída: <!-- o que ele produz -->
+- Importa de: <!-- módulos que usa -->
+
+## API Pública
+
+```typescript
+// Assinaturas principais
+```
+
+## Exemplo de Uso
+
+```typescript
+
+```
+
+## Testes
+
+<!-- Onde estão os testes e como rodá-los -->

package/Docs/templates/guia.md

@@ -0,0 +1,28 @@
+---
+Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
+tags: [guia]
+status: rascunho
+created: {{date}}
+---
+
+# Título do Guia
+
+## Objetivo
+
+<!-- O que este guia ensina? -->
+
+## Passo a Passo
+
+1. <!-- passo 1 -->
+2. <!-- passo 2 -->
+3. <!-- passo 3 -->
+
+## Exemplos
+
+```bash
+# Comandos de exemplo
+```
+
+## Referências
+
+- Links para notas relacionadas

package/README.md

@@ -8,9 +8,9 @@ Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (lice
 
 </div>
 
-Caso queira ajudar com relatorios de bugs e erros ou com sugesões entre em contato por esse e-mail abaixo.
+Caso queira ajudar com relatórios de bugs e erros ou com sugestões, entre em contato pelo e-mail abaixo.
 
-[ProtonMail](mailto:mahoraga.civil062@passinbox.com)
+[ProtonMail](mailto:mahoraga.able522@passfwd.com)
 
 ---
 
@@ -43,7 +43,9 @@ mahoraga diagnosticar --json > relatorio.json
 | `guardian` | Monitoramento de integridade com GPG | `mahoraga guardian --accept-baseline` |
 | `fix-types` | Corrigir tipos inseguros (`any`/`unknown`) | `mahoraga fix-types --target src` |
 | `formatar` | Formatação automática de código | `mahoraga formatar --write` |
+| `formatters` | Gerenciamento de formatadores | `mahoraga formatters list` |
 | `podar` | Remover arquivos órfãos e código morto | `mahoraga podar` |
+| `otimizar-svg` | Otimizar arquivos SVG | `mahoraga otimizar-svg --write` |
 | `names` | Extração e renomeação em massa de variáveis | `mahoraga names --scan` |
 | `imports` | Gerenciar aliases de import (`@/`) | `mahoraga imports --scan` |
 | `barrels` | Gerenciar barrels (`index.ts`) | `mahoraga barrels --generate` |
@@ -92,7 +94,6 @@ mahoraga guardian --json               # saída JSON estruturada
 ```bash
 mahoraga github-actions scan           # GitHub Actions
 mahoraga github-actions gate --threshold 80  # quality gate
-mahoraga github-actions app --port 3000      # servidor GitHub App
 mahoraga gitlab-ci scan                # GitLab CI
 mahoraga circleci scan                 # CircleCI
 mahoraga jenkins scan                  # Jenkins
@@ -120,6 +121,7 @@ mahoraga fix-types --interactive       # modo interativo
 mahoraga formatar --write              # formatar código
 mahoraga formatar --check              # apenas verificar
 mahoraga podar                         # remover arquivos órfãos
+mahoraga otimizar-svg --write          # otimizar SVGs
 mahoraga names --scan                  # extrair nomes de variáveis
 mahoraga names --apply                 # aplicar renomeações
 mahoraga reverter listar               # listar reversões disponíveis
@@ -140,7 +142,6 @@ mahoraga marketplace list              # listar instalados
 ### Utilitários
 
 ```bash
-mahoraga otimizar-svg --write          # otimizar SVGs
 mahoraga imports --scan                # escanear aliases de import
 mahoraga imports --apply               # aplicar correções de import
 mahoraga barrels --scan                # preview de barrels
@@ -158,7 +159,8 @@ mahoraga atualizar --global            # auto-update
 
 - **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
+- **14 analisadores de linguagem**: JS, TS, React, CSS, CSS-in-JS, HTML, SVG, XML, Tailwind, Python, Shell, SQL, Go, Rust, PHP
+- **5 analisadores de CI/CD**: GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure Pipelines
 - **Detecção de bugs via ML**: 8 padrões com pontuação Bayesiana
 - **Registro inteligente**: descoberta automática de analistas built-in e customizados
 - **Análise de monorepos**: pnpm-workspace, lerna, nx, turbo
@@ -168,7 +170,7 @@ mahoraga atualizar --global            # auto-update
 - **Guardian**: monitoramento contínuo com assinatura GPG (Ed25519), baselines criptográficos e verificação de integridade
 - **Fix Types**: correção automática de `any` e `unknown`
 - **Poda inteligente**: identificação e remoção de arquivos órfãos e código morto
-- **Formatação**: formatação automática do código
+- **Formatação**: formatação automática do código com supressão inline via `@mahoraga-disable`
 - **Names/Rename**: extração e renomeação em massa de variáveis
 - **Reverter**: rollback de movimentações aplicadas
 - **Imports**: gerenciamento de aliases de import
@@ -183,7 +185,7 @@ mahoraga atualizar --global            # auto-update
 
 ### Integrações CI/CD
 
-- **GitLab CI / CircleCI / Jenkins / Azure Pipelines**: análise de pipelines
+- **GitHub Actions / GitLab CI / CircleCI / Jenkins / Azure Pipelines**: análise de pipelines com detectores e correções específicos
 - **Conversão** entre plataformas de CI/CD
 
 ### Extensível
@@ -213,7 +215,7 @@ npx mahoraga --help
 ### Verificar Instalação
 
 ```bash
-mahoraga --version                    # v0.14.6
+mahoraga --version                    # v0.15.1
 mahoraga --help                       # lista todos os comandos
 mahoraga analistas --json             # analistas disponíveis
 ```
@@ -222,20 +224,176 @@ mahoraga analistas --json             # analistas disponíveis
 
 ## Configuração
 
-O Mahoraga lê um arquivo `mahoraga.config.json` na raiz do seu projeto (ou variáveis de ambiente).
+O Mahoraga lê um arquivo `mahoraga.config.json` na raiz do seu projeto. A configuração usa **deep merge** com esta precedência (maior para menor):
+1. CLI flags / environment variables (`MAHORAGA_*`)
+2. `mahoraga.config.json` (ou `src/config.json` como fallback)
+3. System defaults (hardcoded)
+
+### Comportamento de Merge
+
+- **Objetos** (`languages`, `suppress`, `rules`, `detectorMarkdown`, `autoFix`, `ANALISE_LIMITES`, `nameConventions`): faz merge recursivo — você pode definir apenas os campos que deseja sobrescrever; os demais mantêm os defaults.
+- **Arrays** (`exclude`): são **aditivos** — os padrões que você definir em `exclude` são adicionados aos defaults do sistema, não os substituem. Se você quer excluir `temp/**` além dos defaults, basta incluir `"exclude": ["temp/**"]`.
+- **Primitivos** (`locale`, `verbose`, `LOG_LEVEL`, `GUARDIAN_ENABLED`, etc.): substituem o valor default quando definidos.
+- **`suppress.paths` e `suppress.filePatterns`**: substituem a lista de supressão (não é merge).
 
-### Configuração Mínima
+### Exemplo Completo
 
-```json
+```jsonc
 {
-  "locale": "pt",
-  "verbose": true,
-  "exclude": ["node_modules/**", "dist/**", "coverage/**", ".git/**"],
-  "languageSupport": {
+  // === LOCALIDADE ===
+  "locale": "pt",                        // Idioma: pt, en, zh, ja
+
+  // === LOG E DEBUG ===
+  "verbose": false,                      // Saída verbosa
+  "LOG_LEVEL": "info",                   // Nível: erro, aviso, info, debug
+  "LOG_ESTRUTURADO": false,              // Logs em JSON estruturado
+  "DEV_MODE": false,                     // Modo desenvolvimento
+
+  // === LINGUAGENS ===
+  "languages": {                         // Habilita/desabilita analisadores
     "javascript": { "enabled": true },
     "typescript": { "enabled": true },
+    "react": { "enabled": true },
     "html": { "enabled": true },
-    "css": { "enabled": true }
+    "css": { "enabled": true },
+    "scss": { "enabled": false },
+    "sass": { "enabled": false },
+    "css-in-js": { "enabled": false },
+    "tailwind": { "enabled": false },
+    "xml": { "enabled": true },
+    "svg": { "enabled": false },
+    "python": { "enabled": false },
+    "shell": { "enabled": false },
+    "sql": { "enabled": false },
+    "go": { "enabled": false },
+    "rust": { "enabled": false },
+    "php": { "enabled": false },
+    "astro": { "enabled": false },
+    "gradle": { "enabled": false }
+  },
+
+  // === INCLUDE/EXCLUDE ===
+  "exclude": [                           // Glob patterns para excluir do scan
+    "node_modules/**", "dist/**", "build/**", "coverage/**",
+    ".git/**", ".next/**", ".turbo/**", ".vercel/**",
+    "**/*.min.js", "**/*.min.css", "**/*.log", "**/*.lock",
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
+    "**/.mahoraga/**"
+  ],
+
+  // === SUPRESSÃO DE OCORRÊNCIAS ===
+  "suppress": {
+    "rules": ["no-console"],             // Suprimir regras específicas
+    "severity": { "some-rule": "warning" }, // Override de severidade
+    "paths": ["**/test/**"],             // Suprimir por caminho
+    "filePatterns": ["*.test.ts"]        // Suprimir por padrão de arquivo
+  },
+
+  // === REGRAS PERSONALIZADAS ===
+  "rules": {
+    "nome-da-regra": {
+      "severity": "error",               // error, warning, info, off
+      "exclude": ["**/generated/**"],    // Exclusão por glob
+      "allowTestFiles": false            // Permitir em testes
+    }
+  },
+
+  // === GUARDIAN (INTEGRIDADE) ===
+  "GUARDIAN_ENABLED": true,              // Habilitar Guardian
+  "GUARDIAN_ENFORCE_PROTECTION": true,   // Impedir alterações não autorizadas
+  "GUARDIAN_ALLOW_ADDS": false,          // Permitir adição de arquivos
+  "GUARDIAN_ALLOW_CHG": false,           // Permitir modificação de arquivos
+  "GUARDIAN_ALLOW_DELS": false,          // Permitir deleção de arquivos
+
+  // === WORKERS (PARALELISMO) ===
+  "WORKER_POOL_ENABLED": true,           // Habilitar worker pool
+  "WORKER_POOL_MAX_WORKERS": 0,          // Máx workers (0 = auto)
+  "WORKER_POOL_BATCH_SIZE": 10,          // Arquivos por lote
+  "WORKER_POOL_AUTO_THRESHOLD": 50,      // Threshold para auto-pool
+
+  // === ANÁLISE ===
+  "ANALISE_INCREMENTAL_ENABLED": false,  // Análise incremental
+  "ANALISE_CACHE_ENABLED": false,        // Cache de análise
+  "ANALISE_CACHE_TTL_MS": 86400000,      // TTL do cache (24h)
+  "ANALISE_METRICAS_ENABLED": true,      // Coleta de métricas
+  "ANALISE_PRIORIZACAO_ENABLED": true,   // Priorização de ocorrências
+  "ANALISE_TIMEOUT_POR_ANALISTA_MS": 30000, // Timeout por analista
+  "SCAN_ONLY": false,                    // Modo scan-only (sem correções)
+  "COMPACT_MODE": false,                 // Modo compacto
+
+  // === LIMITES DE ANÁLISE ===
+  "ANALISE_LIMITES": {
+    "FUNCOES_LONGAS": {
+      "MAX_LINHAS": 30,                  // Máx linhas por função
+      "MAX_PARAMETROS": 4,               // Máx parâmetros
+      "MAX_ANINHAMENTO": 3               // Máx aninhamento if
+    },
+    "CODIGO_FRAGIL": {
+      "MAX_LINHAS_FUNCAO": 30,
+      "MAX_PARAMETROS": 4,
+      "MAX_NESTED_CALLBACKS": 2          // Máx callbacks aninhados
+    }
+  },
+
+  // === RELATÓRIOS ===
+  "REPORT_EXPORT_ENABLED": false,        // Exportar relatórios
+  "REPORT_EXPORT_FULL": false,           // Relatório completo (não diff)
+  "REPORT_OUTPUT_DIR": ".mahoraga/reports",
+  "REPORT_SILENCE_LOGS": false,          // Silenciar logs durante geração
+  "REPORT_STREAM_ENABLED": false,        // Streaming NDJSON
+  "REPORT_STREAM_AUTO_THRESHOLD": 5000,  // Auto-stream para projetos grandes
+  "REPORT_FRAGMENT_OCCURRENCES": 2000,   // Máx ocorrências por fragmento
+  "REPORT_FRAGMENT_FILEENTRIES": 500,    // Máx entradas por fragmento
+
+  // === ESTRUTURA DO PROJETO ===
+  "STRUCTURE_AUTO_FIX": false,           // Auto-fix de violações estruturais
+  "STRUCTURE_CONCURRENCY": 5,            // Concorrência
+  "ESTRUTURA_ARQUIVOS_RAIZ_MAX": 10,     // Máx arquivos na raiz
+  "ESTRUTURA_PLANO_MAX_FILE_SIZE": 262144, // Tam máx para plano (256KB)
+
+  // === CONVENÇÕES DE NOMES ===
+  "nameConventions": {                   // Personalizar nomes de diretórios
+    "typesDirectory": "types",
+    "testsDirectory": "tests",
+    "docsDirectory": "docs",
+    "srcDirectory": "src",
+    "componentsDirectory": "components",
+    "utilsDirectory": "utils",
+    "servicesDirectory": "services",
+    "stylesDirectory": "styles",
+    "assetsDirectory": "assets"
+  },
+
+  // === MARKDOWN DETECTOR ===
+  "detectorMarkdown": {
+    "checkProveniencia": true,           // Verificar headers de proveniência
+    "checkLicenses": true,               // Verificar compatibilidade de licença
+    "checkReferences": true,             // Verificar referências externas
+    "headerLines": 30,                   // Linhas para scan de headers
+    "whitelist": {
+      "paths": [],
+      "patterns": [],
+      "dirs": []
+    },
+    "whitelistMode": "merge"             // merge | replace
+  },
+
+  // === SEGURANÇA ===
+  "SAFE_MODE": true,                     // Modo seguro
+  "ALLOW_PLUGINS": false,                // Permitir carregamento de plugins
+  "ALLOW_EXEC": false,                   // Permitir execução de código
+  "ALLOW_MUTATE_FS": true,               // Permitir mutação do filesystem
+
+  // === AUTO-FIX ===
+  "autoFix": {                           // Configuração de correção automática
+    "mode": "balanced",                  // balanced | conservative | aggressive
+    "minConfidence": 75,                 // Confiança mínima (0-100)
+    "maxFixesPerArquivo": 5,             // Máx correções por arquivo
+    "createBackup": true,                // Criar backup (.local.bak)
+    "validateAfterFix": true,            // Validar após correção
+    "allowedCategories": [
+      "security", "performance", "style", "documentation"
+    ]
   }
 }
 ```
@@ -244,10 +402,76 @@ O Mahoraga lê um arquivo `mahoraga.config.json` na raiz do seu projeto (ou vari
 
 | Variável | Descrição | Padrão |
 |----------|-----------|--------|
-| `LOG_LEVEL` | Nível de log | `info` |
-| `LOG_ESTRUTURADO` | Logs em JSON | `false` |
-| `MAHORAGA_DEBUG` | Modo debug | não definido |
+| `LOG_LEVEL` | Nível de log (`erro`, `aviso`, `info`, `debug`) | `info` |
+| `LOG_ESTRUTURADO` | Logs em JSON estruturado | `false` |
+| `MAHORAGA_DEBUG` | Ativa modo debug | não definido |
 | `MAHORAGA_STATE_DIR` | Diretório de estado | `.mahoraga` |
+| `MAHORAGA_VERBOSE` | Saída verbosa | `false` |
+| `MAHORAGA_SAFE_MODE` | Modo segurança (`0` desativa) | `1` |
+| `MAHORAGA_ALLOW_PLUGINS` | Permite plugins (`1` ativa) | `0` |
+| `MAHORAGA_ALLOW_EXEC` | Permite execução (`1` ativa) | `0` |
+| `MAHORAGA_DEV` | Ativa modo dev | não definido |
+
+---
+
+## Supressão Inline (`@mahoraga-disable`)
+
+Além da supressão por configuração, o Mahoraga suporta **supressão inline** via comentários no código fonte. Funciona tanto para analistas quanto para o formatador.
+
+### Formatos
+
+| Diretiva | Escopo | Exemplo |
+|----------|--------|---------|
+| `@mahoraga-disable-next-line <regras>` | Próxima linha | `// @mahoraga-disable-next-line pontuacao-repetida` |
+| `@mahoraga-disable <regras>` | Bloco (até `@mahoraga-enable`) | `// @mahoraga-disable formatador` |
+| `@mahoraga-enable <regras>` | Fim de bloco | `// @mahoraga-enable formatador` |
+| `@mahoraga-disable-all` | Bloco total | `// @mahoraga-disable-all` |
+| `@mahoraga-enable-all` | Fim de bloco total | `// @mahoraga-enable-all` |
+
+### Sintaxes de comentário suportadas
+
+| Linguagem | Sintaxe |
+|-----------|---------|
+| JS/TS/CSS | `// @mahoraga-disable regra` / `/* @mahoraga-disable regra */` |
+| Python/Shell/YAML | `# @mahoraga-disable regra` |
+| SQL | `-- @mahoraga-disable regra` |
+| INI | `; @mahoraga-disable regra` |
+| HTML | `<!-- @mahoraga-disable regra -->` |
+
+### Regras do formatador
+
+| Regra | Efeito |
+|-------|--------|
+| `pontuacao-repetida` | Impede colapso de pontuação repetida (`;;`, ` ...`, etc.) |
+| `espacamento-incorreto` | Impede correção de espaçamento ao redor de pontuação |
+| `formatador` | Desativa todas as correções do formatador na linha/bloco |
+| `analista-formatador` | Desativa apenas o analista de verificação de formatação |
+| `*` | Desativa regras de todos os sistemas |
+
+### Exemplos
+
+```typescript
+// @mahoraga-disable-next-line pontuacao-repetida
+const x = a;;  // <-- os dois ;; serão preservados
+
+// @mahoraga-disable formatador
+function exemplo() {
+  const url = "https://example.com/path?v=1&x=2";
+  return url;
+}
+// @mahoraga-enable formatador
+```
+
+```bash
+# @mahoraga-disable-next-line espacamento-incorreto
+case $x in a) echo "a" ;; esac  # <-- ;; preservado
+```
+
+```html
+<!-- @mahoraga-disable formatador -->
+<pre>  texto  com  espaços  intencionais  </pre>
+<!-- @mahoraga-enable formatador -->
+```
 
 ---
 
@@ -270,8 +494,12 @@ npm run lint           # ESLint
 |-----------|--------|---------|
 | JavaScript | Babel | Nativo |
 | TypeScript | Babel | Nativo |
+| React/JSX | Babel | Nativo |
 | HTML | htmlparser2 | Nativo |
 | CSS | postcss | Nativo |
+| CSS-in-JS | postcss | Nativo |
+| Tailwind CSS | Heurístico | Nativo |
+| SVG | Heurístico | Nativo |
 | XML | fast-xml-parser | Nativo |
 | Python | Heurístico | Nativo |
 | PHP | Heurístico | Nativo |
@@ -284,12 +512,27 @@ npm run lint           # ESLint
 
 ## Qualidade
 
-- TypeScript 7.0+ (compilador nativo Go/Corsa): type-safe
-- Testes com Vitest: cobertura target > 90%
-- ESLint 10.x: configuração strict
-- Worker pool: processamento paralelo
-- i18n: PT, EN, ZH, JA
-- Schema versioning: relatórios versionados
+- **TypeScript estrito**: `strict: true`, `verbatimModuleSyntax: true`
+- **Testes com Vitest**: ~3300 testes em ~240 arquivos
+- **ESLint 10.x**: configuração strict
+- **Worker pool**: processamento paralelo
+- **i18n**: PT, EN, ZH, JA
+- **Schema versioning**: relatórios versionados
+- **Documentação viva**: `Docs/` em formato Obsidian vault
+
+---
+
+## Documentação
+
+A documentação completa do projeto está disponível em `Docs/` no formato **Obsidian vault**:
+
+- **Arquitetura**: camadas, fluxos, diagramas, ADRs
+- **Componentes**: documentação de todos os módulos
+- **Guias**: contribuição, testes, referência de comandos
+- **Glossário**: termos do domínio de A a Z
+- **Referências**: links, specs, configurações
+
+Abra `Docs/` como vault no [Obsidian](https://obsidian.md/) para navegação completa com wikilinks.
 
 ---
 
@@ -297,7 +540,7 @@ npm run lint           # ESLint
 
 Contribuições são bem-vindas! Como o projeto não está mais no GitHub:
 
-1. Entre em contato pelo e-mail: [ProtonMail](mailto:mahoraga.civil062@passinbox.com)
+1. Entre em contato pelo e-mail: [ProtonMail](mailto:mahoraga.able522@passfwd.com)
 2. Envie patches ou sugestões por e-mail
 3. Reporte bugs com descrição detalhada e exemplo mínimo
 

package/dist/analysts/detectors/detector-bugs-ml.js

@@ -2,6 +2,7 @@ import { parse as babelParse } from '@babel/parser';
 import traverse from '@babel/traverse';
 import * as t from '@babel/types';
 import { getMessages } from '../../core/messages/index.js';
+import { isWhitelistedConstant } from '../../shared/helpers/index.js';
 const MAX_MESSAGE_PREVIEW_LENGTH = 60;
 const BUG_PATTERNS = [
     {
@@ -224,6 +225,10 @@ const BUG_PATTERNS = [
             const matches = content.matchAll(magicNumPattern);
             const results = [];
             for (const m of matches) {
+                const value = parseInt(m[0], 10);
+                if (isWhitelistedConstant(value, [])) {
+                    continue;
+                }
                 const line = contarLinhasAtePos(content, m.index);
                 const lineContent = content.split('\n')[line - 1] || '';
                 if (!lineContent.includes('const') && !lineContent.includes('let') && !lineContent.includes('var') && !lineContent.includes('//') && !lineContent.includes('/*')) {

package/dist/analysts/js-ts/registrar.js

@@ -1,6 +1,6 @@
 const detectoresJsTs = [];
 export function registrarDetectorJsTs(detector) {
-    if (!detector || !detector.nome) {
+    if (!detector?.nome) {
         return;
     }
     const exists = detectoresJsTs.some(d => d.nome === detector.nome);

package/dist/analysts/plugins/detector-markdown.js

@@ -8,9 +8,9 @@ const LICENCA_PADROES = {
     referenciasRisco: [/Stack\s*Overflow/i, /(?:^|https?:\/\/|\/\/)(?:[^\/\s@]+\.)?stackoverflow\.com(?::\d+)?(?:[\/?#]|$)/i, /\bassign\b/i, /\bcession\b/i]
 };
 const PADRAO_LISTA_BRANCA = {
-    paths: ['.github/copilot-instructions.md', 'docs/POLICY-PROVENIENCIA.md', 'docs/partials/AVISO-PROVENIENCIA.md'],
+    paths: ['.github/copilot-instructions.md', 'docs/POLICY-PROVENIENCIA.md', 'docs/partials/AVISO-PROVENIENCIA.md', 'README.md'],
     patterns: ['**/reports/**', 'docs/history/**', 'tests/**', 'tmp*.md'],
-    dirs: ['pre-public', 'preview-mahoraga', '.abandonados', '.deprecados', 'reports']
+    dirs: ['pre-public', 'preview-mahoraga', '.abandonados', '.deprecados', 'reports', 'docs']
 };
 function createRiskRegex() {
     const allPadroes = [...LICENCA_PADROES.incompativeis, ...LICENCA_PADROES.cessaoDireitos, ...LICENCA_PADROES.referenciasRisco].map(raiz => raiz.source).join('|');