@mocoto/mahoraga 0.15.0 → 0.15.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/Docs/.obsidian/app.json +7 -0
  2. package/Docs/.obsidian/appearance.json +8 -0
  3. package/Docs/.obsidian/community-plugins.json +28 -0
  4. package/Docs/.obsidian/core-plugins-migration.json +18 -0
  5. package/Docs/.obsidian/core-plugins.json +73 -0
  6. package/Docs/.obsidian/graph.json +22 -0
  7. package/Docs/.obsidian/workspace.json +196 -0
  8. package/Docs/01-arquitetura/ADR-001-estrutura-testes.md +31 -0
  9. package/Docs/01-arquitetura/_index.md +152 -0
  10. package/Docs/02-componentes/_index.md +294 -0
  11. package/Docs/02-componentes/configuracao.md +110 -0
  12. package/Docs/02-componentes/supressao-inline.md +88 -0
  13. package/Docs/03-guias/_index.md +173 -0
  14. package/Docs/03-guias/contribuindo.md +71 -0
  15. package/Docs/03-guias/testes.md +133 -0
  16. package/Docs/04-glossario/_index.md +29 -0
  17. package/Docs/04-glossario/termos.md +247 -0
  18. package/Docs/05-referencias/_index.md +88 -0
  19. package/Docs/06-feedbacks/feedback.md +74 -0
  20. package/Docs/Sem t/303/255tulo.base" +3 -0
  21. package/Docs/Sem t/303/255tulo.md +0 -0
  22. package/Docs/_home.md +140 -0
  23. package/Docs/partials/AVISO-PROVENIENCIA.md +3 -0
  24. package/Docs/templates/ADR.md +24 -0
  25. package/Docs/templates/componente.md +34 -0
  26. package/Docs/templates/guia.md +28 -0
  27. package/README.md +269 -26
  28. package/dist/analysts/detectors/detector-bugs-ml.js +5 -0
  29. package/dist/analysts/js-ts/registrar.js +1 -1
  30. package/dist/analysts/plugins/detector-markdown.js +2 -2
  31. package/dist/analysts/react/analysts/analyst-react-hooks.js +30 -15
  32. package/dist/analysts/react/analysts/analyst-react.js +11 -2
  33. package/dist/analysts/react/detectors/detector-react-best-practices.js +7 -4
  34. package/dist/caretakers/caretaker-imports.js +0 -9
  35. package/dist/cli/commands/command-github-actions.js +0 -27
  36. package/dist/cli/diagnostic/filters.js +1 -4
  37. package/dist/core/config/config.js +2 -3
  38. package/dist/core/config/excludes-padrao.js +3 -2
  39. package/dist/core/messages/en/cli/cli-command-github-actions-messages.js +0 -5
  40. package/dist/core/messages/en/github/index.js +0 -1
  41. package/dist/core/messages/ja/cli/cli-command-github-actions-messages.js +0 -5
  42. package/dist/core/messages/ja/github/index.js +0 -1
  43. package/dist/core/messages/pt/cli/cli-command-github-actions-messages.js +0 -5
  44. package/dist/core/messages/pt/github/index.js +0 -1
  45. package/dist/core/messages/zh/cli/cli-command-github-actions-messages.js +0 -5
  46. package/dist/core/messages/zh/github/index.js +0 -1
  47. package/dist/core/registry/file-registry.js +1 -1
  48. package/dist/node.loader.js +0 -2
  49. package/dist/reports/report-structure.js +2 -8
  50. package/dist/shared/formatters/formatters/commons.js +36 -10
  51. package/dist/shared/formatters/formatters/shell.js +6 -3
  52. package/dist/shared/helpers/magic-constants-whitelist.js +14 -1
  53. package/dist/types/analysts/index.js +1 -1
  54. package/dist/types/processing/filters.js +1 -4
  55. package/package.json +31 -32
  56. package/dist/app/github.js +0 -14
  57. package/dist/app/index.js +0 -1
  58. package/dist/core/messages/en/github/github-app-messages.js +0 -9
  59. package/dist/core/messages/ja/github/github-app-messages.js +0 -9
  60. package/dist/core/messages/pt/github/github-app-messages.js +0 -9
  61. package/dist/core/messages/zh/github/github-app-messages.js +0 -9
@@ -0,0 +1,71 @@
1
+ ---
2
+ Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
3
+ tags: [guia]
4
+ status: rascunho
5
+ created: 2026-07-24
6
+ updated: 2026-07-25
7
+ ---
8
+
9
+ # Contribuindo
10
+
11
+ ## Workflow
12
+
13
+ 1. Crie uma branch: `tipo/descricao-curta` (ex: `feat/novo-comando`)
14
+ 2. Faça commits atômicos seguindo [conventional commits](https://www.conventionalcommits.org/)
15
+ 3. Abra um Pull Request com descrição do *porquê*, não apenas do *que*
16
+ 4. PRs devem ser pequenos (máx 200-400 linhas)
17
+
18
+ ## Checklist pré-PR
19
+
20
+ - [ ] `npm run typecheck` passando
21
+ - [ ] `npm test` passando
22
+ - [ ] `npm run build` passando
23
+ - [ ] Cobertura adequada nos arquivos alterados
24
+ - [ ] Mensagens i18n atualizadas em pt, en, zh, ja
25
+ - [ ] Documentação atualizada em `Docs/`
26
+
27
+ ## Convenções
28
+
29
+ - Commits: `tipo(escopo): descrição no imperativo`
30
+ - Tipos: feat, fix, refactor, docs, test, chore
31
+ - Branches: `tipo/issue-123-descricao`
32
+ - NUNCA force push
33
+ - NUNCA use `git add.`: adicione apenas arquivos intencionais
34
+ - Revise `git diff --cached` por segredos antes de commitar
35
+
36
+ ## Estrutura de um Comando
37
+
38
+ ```typescript
39
+ // src/cli/commands/command-exemplo.ts
40
+ import { Command } from 'commander';
41
+
42
+ export function comandoExemplo(aplicarFlagsGlobais: (opts: unknown) => void): Command {
43
+ const cmd = new Command('exemplo').alias('ex')
44
+ .description('Faz algo incrível')
45
+ .option('-t, --target <path>', 'Diretório alvo');
46
+
47
+ cmd.action(async (opts) => {
48
+ aplicarFlagsGlobais(opts);
49
+ // implementação...
50
+ });
51
+
52
+ return cmd;
53
+ }
54
+ ```
55
+
56
+ ## Convenções de i18n
57
+
58
+ Toda mensagem visível ao usuário deve ser adicionada em 4 línguas:
59
+
60
+ - `src/core/messages/pt/ ...`: Português (padrão)
61
+ - `src/core/messages/en/ ...`: Inglês
62
+ - `src/core/messages/zh/ ...`: Chinês
63
+ - `src/core/messages/ja/ ...`: Japonês
64
+
65
+ Mensagens são objetos `as const` exportados e tipados.
66
+
67
+ ## Dependências
68
+
69
+ - **Runtime:** Node.js >=24.16.0
70
+ - **Gerenciador:** npm
71
+ - **Nunca adicione** `@types/*` como dependência de produção: use `devDependencies`
@@ -0,0 +1,133 @@
1
+ ---
2
+ Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
3
+ tags: [guia, testes]
4
+ status: rascunho
5
+ created: 2026-07-24
6
+ updated: 2026-07-25
7
+ ---
8
+
9
+ # Testes
10
+
11
+ ## Stack
12
+
13
+ - **Framework:** Vitest v4
14
+ - **Coverage:** v8 (via `@vitest/coverage-v8`)
15
+ - **Mocks:** `vi.hoisted()` + `vi.mock()` no topo dos arquivos
16
+ - **Organização:** `tests/` espelha `src/` em estrutura de diretórios
17
+ - **Aliases:** Mesma configuração de paths do tsconfig (definidos em `vitest.config.ts`)
18
+
19
+ ## Padrões
20
+
21
+ ### Teste de Comando CLI
22
+
23
+ ```typescript
24
+ import { describe, it, expect, vi, beforeEach } from 'vitest';
25
+
26
+ const mockLog = vi.hoisted(() => ({ info: vi.fn(), erro: vi.fn() }));
27
+
28
+ vi.mock('@core/messages', () => ({
29
+ getMessages: () => ({ log: mockLog, /* ... */ }),
30
+ }));
31
+
32
+ import { comandoFormatar } from '../../../src/cli/commands/command-format.js';
33
+
34
+ describe('comandoFormatar', () => {
35
+ beforeEach(() => { vi.clearAllMocks(); });
36
+
37
+ it('cria comando com nome esperado', () => {
38
+ const cmd = comandoFormatar(vi.fn());
39
+ expect(cmd.name()).toBe('formatar');
40
+ });
41
+
42
+ it('captura erros no scanRepository', async () => {
43
+ const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
44
+ const scanRepo = (await import('@core/execution')).scanRepository as ReturnType<typeof vi.fn>;
45
+ scanRepo.mockRejectedValue(new Error('erro'));
46
+ const cmd = comandoFormatar(vi.fn());
47
+ await cmd.parseAsync([], { from: 'user' });
48
+ expect(mockLog.erro).toHaveBeenCalled();
49
+ exitSpy.mockRestore();
50
+ });
51
+ });
52
+ ```
53
+
54
+ ### Teste com Callback Pattern (Mocks Complexos)
55
+
56
+ ```typescript
57
+ // Para módulos com mocking complexo (ex: createRequire, promisify):
58
+ const mockFn = vi.hoisted(() => vi.fn().mockResolvedValue([]));
59
+
60
+ vi.mock('node:module', () => ({
61
+ createRequire: () => (id: string) => {
62
+ if (id === 'license-checker') return { init: mockFn };
63
+ return require(id);
64
+ },
65
+ }));
66
+
67
+ vi.mock('node:util', () => ({ promisify: () => (fn: any) => fn }));
68
+
69
+ // Import dinâmico após os mocks
70
+ const mod = await import('../../src/licenses/generate-notices.js');
71
+ ```
72
+
73
+ ### Teste de Módulo com FS
74
+
75
+ ```typescript
76
+ import fs from 'node:fs';
77
+ import os from 'node:os';
78
+ import path from 'node:path';
79
+
80
+ let tmpDir: string;
81
+
82
+ beforeEach(() => {
83
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mahoraga-test-'));
84
+ });
85
+
86
+ afterEach(() => {
87
+ fs.rmSync(tmpDir, { recursive: true, force: true });
88
+ });
89
+ ```
90
+
91
+ ### Teste de Tipos
92
+
93
+ ```typescript
94
+ import { describe, it, expectTypeOf } from 'vitest';
95
+ import type { MeuTipo } from '../../src/types/index.js';
96
+
97
+ describe('MeuTipo', () => {
98
+ it('deve ser string', () => {
99
+ expectTypeOf<MeuTipo>().toBeString();
100
+ });
101
+ });
102
+ ```
103
+
104
+ ## Cobertura
105
+
106
+ ```bash
107
+ npm run coverage # relatório completo
108
+ npx vitest run --coverage --reporter=text # apenas terminal
109
+ npx vitest run --coverage --reporter=html # HTML interativo
110
+ ```
111
+
112
+ ### Alvo
113
+
114
+ - Cobertura geral target: 56%+ statements
115
+ - Novos arquivos: 80%+ statements
116
+ - Módulos críticos (licenses, vulnerabilities, guardian): 90%+
117
+
118
+ ## Dicas Avançadas
119
+
120
+ - `parseAsync([], { from: 'user' })`: Commander v15 não aceita args posicionais
121
+ - `vi.spyOn(process, 'exit')`: sempre restaurar com `.mockRestore()` no afterEach
122
+ - `vi.hoisted()` para variáveis que precisam existir antes dos mocks serem avaliados
123
+ - Testes de FS real usar `os.tmpdir()` + limpeza em `afterEach`
124
+ - Mocks de `@core/messages` são os mais comuns: criar helper se repetir muito
125
+ - Para testar barrels (index.ts), importar o barrel e verificar se as exportações existem
126
+
127
+ ## Debug
128
+
129
+ ```bash
130
+ npx vitest --reporter=verbose # log detalhado
131
+ npx vitest --reporter=json # saída JSON
132
+ npx vitest run tests/meu-teste.test.ts --reporter=verbose
133
+ ```
@@ -0,0 +1,29 @@
1
+ ---
2
+ Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
3
+ tags: [moc, glossario]
4
+ created: 2026-07-24
5
+ ---
6
+
7
+ # Glossário
8
+
9
+ ## Termos do Domínio
10
+
11
+ | Termo | Definição |
12
+ |-------|-----------|
13
+ | **Analyst** | Analisador especializado que processa um aspecto do código (AST, dependências, etc.) |
14
+ | **Caretaker** | Módulo que aplica transformações automáticas no código fonte |
15
+ | **Guardian** | Pipeline de integridade que verifica baseline vs estado atual |
16
+ | **Baseline** | Estado de referência do projeto usado pelo Guardian |
17
+ | **Registry** | Registro central de analysts com descoberta automática |
18
+ | **Runtime** | Adaptador de ambiente (Node, Deno, Bun) |
19
+ | **MOC** | Map of Content: nota índice que linka notas relacionadas |
20
+ | **ADR** | Architecture Decision Record: registro de decisão arquitetural |
21
+ | **MCP** | Model Context Protocol: protocolo para agentes de IA acessarem ferramentas |
22
+
23
+ ## Tags Utilizadas
24
+
25
+ - `#moc`: Nota do tipo Mapa de Conteúdo
26
+ - `#adr`: Architecture Decision Record
27
+ - `#guia`: Guia de desenvolvimento
28
+ - `#glossario`: Entrada de glossário
29
+ - `#termo`: Definição de termo
@@ -0,0 +1,247 @@
1
+ ---
2
+ Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
3
+ tags: [glossario, termo]
4
+ created: 2026-07-24
5
+ updated: 2026-07-25
6
+ ---
7
+
8
+ # Termos do Domínio
9
+
10
+ ## A
11
+
12
+ ### ADR (Architecture Decision Record)
13
+
14
+ Registro de decisão arquitetural. Documenta o contexto, a decisão tomada, consequências e alternativas consideradas. Usa o template em `templates/ADR.md`.
15
+
16
+ ### Advisor
17
+
18
+ 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`).
19
+
20
+ ### Analyst
21
+
22
+ 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.
23
+
24
+ ### Archetype
25
+
26
+ Padrão arquitetural detectado pelo sistema de análise. Usado para classificar projetos e sugerir boas práticas específicas.
27
+
28
+ ### Autodiscovery
29
+
30
+ Mecanismo que descobre automaticamente analistas e detectores sem registro manual. Implementado em `src/analysts/registry/autodiscovery.ts`.
31
+
32
+ ### Azure Pipelines
33
+
34
+ Plataforma de CI/CD da Microsoft. O Mahoraga analisa pipelines Azure com detectores e correções específicos.
35
+
36
+ ## B
37
+
38
+ ### Babel
39
+
40
+ Parser de JavaScript/TypeScript usado pelo Mahoraga para análise de AST (Árvore Sintática Abstrata).
41
+
42
+ ### Barrel
43
+
44
+ Arquivo `index.ts` que re-exporta módulos de um diretório. O Mahoraga pode escanear, gerar e gerenciar barrels automaticamente.
45
+
46
+ ### Baseline
47
+
48
+ Estado de referência do projeto usado pelo Guardian para detectar alterações não autorizadas. Armazenado em `.mahoraga/baseline/`.
49
+
50
+ ## C
51
+
52
+ ### Caretaker
53
+
54
+ Módulo que aplica transformações automáticas no código fonte. Exemplo: `caretaker-imports.ts` gerencia aliases de import.
55
+
56
+ ### CircleCI
57
+
58
+ Plataforma de CI/CD. O Mahoraga analisa pipelines CircleCI com detectores e correções.
59
+
60
+ ### CLI
61
+
62
+ Command Line Interface. Interface de linha de comando implementada com Commander.js.
63
+
64
+ ### Compliance
65
+
66
+ Conformidade com standards de segurança e governança. O Mahoraga gera relatórios ISO 27001 e SOC 2.
67
+
68
+ ### Conventional Commits
69
+
70
+ Padrão de mensagens de commit: `tipo(escopo): descrição`. Tipos usados: feat, fix, refactor, docs, test, chore.
71
+
72
+ ### Converter
73
+
74
+ Módulo que converte pipelines entre plataformas de CI/CD (ex: GitHub Actions → GitLab CI).
75
+
76
+ ## D
77
+
78
+ ### Detector
79
+
80
+ Unidade mínima de análise que verifica um aspecto específico do código. Múltiplos detectores compõem um analyst.
81
+
82
+ ### Disclaimer
83
+
84
+ Header SPDX adicionado ao topo de arquivos fonte para declaração de licença. O módulo `licenses/disclaimer.ts` gerencia isso.
85
+
86
+ ## E
87
+
88
+ ### Ed25519
89
+
90
+ Algoritmo de curva elíptica usado pelo Guardian para assinatura GPG. Escolhido por segurança e performance.
91
+
92
+ ## F
93
+
94
+ ### Fix Types
95
+
96
+ Subcomando que corrige automaticamente tipos inseguros (`any` → tipos concretos, `unknown` → tipos específicos).
97
+
98
+ ## G
99
+
100
+ ### GitHub Actions
101
+
102
+ Plataforma de CI/CD do GitHub. O Mahoraga analisa workflows YAML com detectores especializados.
103
+
104
+ ### GitLab CI
105
+
106
+ Plataforma de CI/CD do GitLab. Análise de pipelines `.gitlab-ci.yml`.
107
+
108
+ ### GPG (GNU Privacy Guard)
109
+
110
+ Sistema de criptografia usado pelo Guardian para assinar e verificar baselines de integridade.
111
+
112
+ ### Guardian
113
+
114
+ Pipeline de integridade que compara o baseline com o estado atual do projeto, detectando desvios e alterações suspeitas. Usa assinatura GPG Ed25519.
115
+
116
+ ## I
117
+
118
+ ### i18n
119
+
120
+ Internacionalização. O Mahoraga suporta 4 idiomas: Português (padrão), Inglês, Chinês, Japonês.
121
+
122
+ ### Inquisitor
123
+
124
+ Módulo do core que coordena a execução dos analisadores durante o scan.
125
+
126
+ ## J
127
+
128
+ ### Jenkins
129
+
130
+ Plataforma de CI/CD open-source. O Mahoraga analisa pipelines Jenkins.
131
+
132
+ ## L
133
+
134
+ ### Loader ESM
135
+
136
+ Mecanismo em `src/node.loader.ts` que resolve path aliases em tempo de execução, permitindo imports como `@core/execution`.
137
+
138
+ ## M
139
+
140
+ ### MCP (Model Context Protocol)
141
+
142
+ Protocolo padrão que permite agentes de IA acessarem ferramentas e recursos externos de forma segura.
143
+
144
+ ### Marketplace
145
+
146
+ Sistema de distribuição de analistas comunitários. Comandos: `marketplace search`, `marketplace install`.
147
+
148
+ ### MOC (Map of Content)
149
+
150
+ Nota índice que funciona como hub de navegação, linkando notas relacionadas sobre um mesmo tema. Substitui pastas profundas na documentação.
151
+
152
+ ### Monorepo
153
+
154
+ Repositório com múltiplos projetos. O Mahoraga detecta configurações pnpm-workspace, lerna, nx e turbo.
155
+
156
+ ## N
157
+
158
+ ### NDJSON (Newline Delimited JSON)
159
+
160
+ Formato de streaming usado para projetos grandes. Cada linha é um JSON válido, permitindo processamento incremental.
161
+
162
+ ### npm audit
163
+
164
+ Ferramenta do npm para scan de vulnerabilidades em dependências. Integrada ao módulo `vulnerabilities/`.
165
+
166
+ ## P
167
+
168
+ ### Phantom
169
+
170
+ Arquivo que existe no filesystem mas não é importado por nenhum outro módulo. Detectado pelo detector de phantoms.
171
+
172
+ ### Plugin
173
+
174
+ Extensão do sistema de análise. Plugins built-in: analyst-formatter, detector-documentation, detector-markdown, detector-node.
175
+
176
+ ### Poda (Pruning)
177
+
178
+ Remoção automatizada de arquivos órfãos e código morto. Comando: `mahoraga podar`.
179
+
180
+ ### postcss
181
+
182
+ Parser de CSS usado pelos analisadores CSS e CSS-in-JS.
183
+
184
+ ## R
185
+
186
+ ### Registry
187
+
188
+ Registro central de analysts com descoberta automática via `autodiscovery.ts`. Permite que novos analysts sejam detectados sem registro manual.
189
+
190
+ ### Runtime
191
+
192
+ Camada de abstração do ambiente de execução. Suporta Node.js através do adaptador em `src/core/runtime/`.
193
+
194
+ ## S
195
+
196
+ ### Scanner
197
+
198
+ Motor que percorre o filesystem, identifica arquivos por tipo e coordena a análise. Presente em `core/execution/` e `licenses/scanner.ts`.
199
+
200
+ ### Schema Versioning
201
+
202
+ Sistema de versionamento de schemas de relatórios para compatibilidade retroativa.
203
+
204
+ ### Sentinel
205
+
206
+ Mecanismo do Guardian que monitora continuamente alterações no projeto.
207
+
208
+ ### SOC 2
209
+
210
+ Standard de auditoria de controles organizacionais. Relatório gerado pelo módulo `reports/compliance/`.
211
+
212
+ ### SPDX
213
+
214
+ Software Package Data Exchange. Padrão para comunicação de informações de licenças. Usado pelo módulo `licenses/`.
215
+
216
+ ### Streaming
217
+
218
+ Modo de saída NDJSON para projetos grandes, permitindo processamento incremental sem carregar tudo em memória.
219
+
220
+ ## T
221
+
222
+ ### THIRD-PARTY-NOTICES
223
+
224
+ Arquivo gerado pelo Mahoraga listando todas as licenças de dependências do projeto.
225
+
226
+ ## W
227
+
228
+ ### Worker Pool
229
+
230
+ Sistema de processamento paralelo em `src/core/workers/`. Gerencia fila de tarefas, workers e resultados.
231
+
232
+ ## X
233
+
234
+ ### xxhash
235
+
236
+ Algoritmo de hashing não-criptográfico usado pelo Guardian para hash rápido de arquivos.
237
+
238
+ ## Índice de Tags
239
+
240
+ | Tag | Uso |
241
+ |-----|-----|
242
+ | `#moc` | Nota Mapa de Conteúdo |
243
+ | `#adr` | Architecture Decision Record |
244
+ | `#guia` | Guia de desenvolvimento |
245
+ | `#glossario` | Entrada de glossário |
246
+ | `#termo` | Definição de termo individual |
247
+ | `#componente` | Documentação de componente |
@@ -0,0 +1,88 @@
1
+ ---
2
+ Proveniência e Autoria: Este documento integra o projeto @mocoto/mahoraga (licença MIT-0).
3
+ tags: [moc, referencias]
4
+ created: 2026-07-24
5
+ updated: 2026-07-25
6
+ ---
7
+
8
+ # Referências
9
+
10
+ ## Links Externos
11
+
12
+ ### Dependências Principais
13
+
14
+ | Biblioteca | Uso | Link |
15
+ |------------|-----|------|
16
+ | Commander.js | CLI framework | https://github.com/tj/commander.js |
17
+ | Vitest | Test framework | https://vitest.dev/ |
18
+ | TypeScript | Linguagem | https://www.typescriptlang.org/ |
19
+ | Babel | AST Parser | https://babel.dev/ |
20
+ | postcss | CSS Parser | https://postcss.org/ |
21
+ | htmlparser2 | HTML Parser | https://github.com/fb55/htmlparser2 |
22
+ | fast-xml-parser | XML Parser | https://github.com/NaturalIntelligence/fast-xml-parser |
23
+ | openpgp | GPG/Cryptography | https://openpgpjs.org/ |
24
+ | chalk | Terminal colors | https://github.com/chalk/chalk |
25
+ | ora | Terminal spinners | https://github.com/sindresorhus/ora |
26
+ | p-limit | Concurrency | https://github.com/sindresorhus/p-limit |
27
+ | micromatch | Glob matching | https://github.com/micromatch/micromatch |
28
+ | yaml | YAML parser | https://eemeli.org/yaml/ |
29
+ | xxhashjs | Hashing | https://github.com/pierrec/js-xxhash |
30
+ | dotenv | Environment vars | https://github.com/motdotla/dotenv |
31
+
32
+ ### Convenções e Standards
33
+
34
+ | Recurso | Link |
35
+ |---------|------|
36
+ | Conventional Commits | https://www.conventionalcommits.org/ |
37
+ | MIT-0 License | https://opensource.org/license/mit-0 |
38
+ | SPDX Specification | https://spdx.dev/ |
39
+ | ISO 27001 | https://www.iso.org/standard/27001 |
40
+ | SOC 2 | https://www.aicpa-cima.com/topic/audit-assurance/audit-and-assurance/soc-2 |
41
+ | Obsidian | https://obsidian.md/ |
42
+
43
+ ## Recursos do Projeto
44
+
45
+ | Arquivo | Conteúdo |
46
+ |---------|----------|
47
+ | `AGENTS.md` | Instruções mestre para agentes de IA |
48
+ | `README.md` | README principal do projeto |
49
+ | `package.json` | Dependências, scripts, configurações |
50
+ | `tsconfig.json` | Configuração TypeScript (paths, strict, ES2024) |
51
+ | `vitest.config.ts` | Configuração de testes e aliases |
52
+ | `eslint.config.js` | Configuração ESLint |
53
+ | `mahoraga.config.json` | Configuração do Mahoraga (merge aditivo com defaults) |
54
+ | `THIRD-PARTY-NOTICES.txt` | Atribuições de licenças |
55
+ | `.github/workflows/ci.yml` | CI pipeline |
56
+ | `.github/workflows/publish.yml` | Publicação no npm |
57
+ | `LICENSE` | Licença MIT-0 |
58
+ | `SKILLS.md` | Índice de skills para agentes de IA |
59
+
60
+ ## Arquivos de Configuração
61
+
62
+ ### tsconfig.json (destaques)
63
+
64
+ - **target:** ES2024
65
+ - **module:** NodeNext
66
+ - **moduleResolution:** NodeNext
67
+ - **strict:** true
68
+ - **verbatimModuleSyntax:** true
69
+ - **paths:** ~160+ aliases internos (`@core/*`, `@cli/*`, `@analysts/*`, etc.)
70
+
71
+ ### vitest.config.ts (destaques)
72
+
73
+ - **provider:** v8 coverage
74
+ - **aliases:** mesmos paths do tsconfig
75
+ - **include:** `tests/**/*.test.ts`
76
+ - **coverage exclude:** coverage, dist, `*.d.ts`, node_modules, tests
77
+
78
+ ## Comandos npm
79
+
80
+ ```bash
81
+ npm run build # compilar TypeScript
82
+ npm run typecheck # verificar tipos
83
+ npm test # rodar testes
84
+ npm run coverage # cobertura de testes
85
+ npm run lint # ESLint
86
+ npm run formatar # auto-formatação
87
+ npm run diagnosticar # auto-análise do mahoraga
88
+ ```
@@ -0,0 +1,74 @@
1
+ # Feedback — Análise de Relatórios do Linter
2
+
3
+ ## Resumo
4
+
5
+ 3 relatórios analisados (`erro-001.json`, `aviso-001.json`, `info-001.json`). Nenhum problema real encontrado — todos são falsos positivos ou itens puramente informativos.
6
+
7
+ ---
8
+
9
+ ## Falsos Positivos
10
+
11
+ ### 1. `markdown-falta-proveniencia` (erro-001.json, 9 ocorrências)
12
+
13
+ **Disparo em**: `Docs/*.md`, `README.md`
14
+
15
+ **Problema**: O linter exige aviso de "Proveniência e Autoria" nas primeiras linhas de todo `.md`. Esse disclaimer é pertinente para instruções de agente (`AGENTS.md`, skills), mas não para documentação de usuário (`Docs/`, `README.md`).
16
+
17
+ **Sugestão**: Ignorar a pasta `Docs/` e `README.md`, ou criar um allowlist/denylist de diretórios para essa regra.
18
+
19
+ ### 2. `codigo-fragil` — shebang ausente (aviso-001.json, husky.sh)
20
+
21
+ **Disparo em**: `.husky/_/husky.sh`
22
+
23
+ **Problema**: O arquivo é gerado automaticamente pelo husky. Arquivos gerados por ferramentas externas não devem ser escaneados.
24
+
25
+ **Sugestão**: Adicionar `.husky/` ao ignore pattern, ou criar um arquivo de configuração `.linterignore`.
26
+
27
+ ### 3. `tailwindcss/regra` — left-0 + right-0 (aviso-001.json, Header.tsx:47)
28
+
29
+ **Disparo em**: `src/app/components/Header.tsx:47`
30
+
31
+ **Problema**: `left-0` + `right-0` em elemento `absolute` é padrão legítimo do Tailwind para esticar o elemento horizontalmente. Não é conflito.
32
+
33
+ **Sugestão**: A regra deve entender que `left-0` + `right-0` em conjunto com `position: absolute/fixed` é intencional e válido. Ignorar quando detectar `absolute` ou `fixed` no mesmo elemento.
34
+
35
+ ### 4. `react/regra` — dangerouslySetInnerHTML (aviso-001.json, json-ld.tsx:17 e 23)
36
+
37
+ **Disparo em**: `src/app/components/json-ld.tsx:17,23`
38
+
39
+ **Problema**: O componente json-ld intencionalmente usa `dangerouslySetInnerHTML` para injetar JSON-LD schema.org. É o padrão recomendado pela documentação do Next.js para SEO.
40
+
41
+ **Sugestão**: Permitir esse padrão quando o componente tiver nome sugestivo (ex: contendo "json-ld", "schema", "structured-data") ou via suppress comment.
42
+
43
+ ### 5. `codigo-fragil` / `boa-pratica-ausente` — shell script boas práticas (info-001.json, husky.sh)
44
+
45
+ **Disparo em**: `.husky/_/husky.sh` — 6 ocorrências (`set -e`, `set -u`, `IFS`, `trap`, `main()`, `command -v`, debug mode, validação de argumentos)
46
+
47
+ **Problema**: Mesmo que o item 2 — arquivo gerado por ferramenta. Além disso, `husky.sh` é um script auxiliar que não é executado diretamente pelo usuário.
48
+
49
+ **Sugestão**: Ignorar `.husky/` completamente no escaneamento.
50
+
51
+ ### 6. `problema-documentacao` — magic-constants (info-001.json, ~25 ocorrências)
52
+
53
+ **Disparo em**: Quase todos os arquivos `src/app/`, `src/lib/`, `vercel.ts`, `next.config.ts`, `src/proxy.ts`
54
+
55
+ **Problema**: Números como `86400` (segundos em 1 dia) ou valores de configuração são detectados como "magic constants". Muitos desses são valores de configuração autoexplicativos ou já estão próximos do uso.
56
+
57
+ **Sugestão**: A regra é muito barulhenta. Recomenda-se usar um limiar mais alto de confiança, ou filtrar valores que são amplamente conhecidos (ex: `60`, `3600`, `86400`, `1000`). Alternativamente, agrupar por arquivo em vez de listar cada ocorrência individualmente.
58
+
59
+ ---
60
+
61
+ ## Sugestões Gerais para o Linter
62
+
63
+ | # | Sugestão |
64
+ |---|----------|
65
+ | 1 | Criar um mecanismo de `ignore` (arquivo `.linterignore` ou comentários `// linter-ignore`) |
66
+ | 2 | Ignorar diretórios de ferramentas: `.husky/`, `.next/`, `node_modules/` |
67
+ | 3 | Ignorar `Docs/` e `README.md` para regras de disclaimer de agente |
68
+ | 4 | Reduzir verbose de regras de "magic constants" — consolidar ocorrências por arquivo |
69
+ | 5 | Adicionar contexto de CSS: `left-0 + right-0` não é conflito quando `position` é `absolute/fixed` |
70
+ | 6 | Adicionar allowlist de padrões para `dangerouslySetInnerHTML` (json-ld, schema, analytics snippets) |
71
+
72
+ ---
73
+
74
+ *Gerado em 2026-07-25 com base na análise dos relatórios `erro-001.json`, `aviso-001.json` e `info-001.json`.*
@@ -0,0 +1,3 @@
1
+ views:
2
+ - type: table
3
+ name: Tabela
File without changes