@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.
- package/Docs/.obsidian/app.json +7 -0
- package/Docs/.obsidian/appearance.json +8 -0
- package/Docs/.obsidian/community-plugins.json +28 -0
- package/Docs/.obsidian/core-plugins-migration.json +18 -0
- package/Docs/.obsidian/core-plugins.json +73 -0
- package/Docs/.obsidian/graph.json +22 -0
- package/Docs/.obsidian/workspace.json +196 -0
- package/Docs/01-arquitetura/ADR-001-estrutura-testes.md +31 -0
- package/Docs/01-arquitetura/_index.md +152 -0
- package/Docs/02-componentes/_index.md +294 -0
- package/Docs/02-componentes/configuracao.md +110 -0
- package/Docs/02-componentes/supressao-inline.md +88 -0
- package/Docs/03-guias/_index.md +173 -0
- package/Docs/03-guias/contribuindo.md +71 -0
- package/Docs/03-guias/testes.md +133 -0
- package/Docs/04-glossario/_index.md +29 -0
- package/Docs/04-glossario/termos.md +247 -0
- package/Docs/05-referencias/_index.md +88 -0
- package/Docs/06-feedbacks/feedback.md +74 -0
- package/Docs/Sem t/303/255tulo.base" +3 -0
- package/Docs/Sem t/303/255tulo.md +0 -0
- package/Docs/_home.md +140 -0
- package/Docs/partials/AVISO-PROVENIENCIA.md +3 -0
- package/Docs/templates/ADR.md +24 -0
- package/Docs/templates/componente.md +34 -0
- package/Docs/templates/guia.md +28 -0
- package/README.md +269 -26
- package/dist/analysts/detectors/detector-bugs-ml.js +5 -0
- package/dist/analysts/js-ts/registrar.js +1 -1
- package/dist/analysts/plugins/detector-markdown.js +2 -2
- package/dist/analysts/react/analysts/analyst-react-hooks.js +30 -15
- package/dist/analysts/react/analysts/analyst-react.js +11 -2
- package/dist/analysts/react/detectors/detector-react-best-practices.js +7 -4
- package/dist/caretakers/caretaker-imports.js +0 -9
- package/dist/cli/commands/command-github-actions.js +0 -27
- package/dist/cli/diagnostic/filters.js +1 -4
- package/dist/core/config/config.js +2 -3
- package/dist/core/config/excludes-padrao.js +3 -2
- package/dist/core/messages/en/cli/cli-command-github-actions-messages.js +0 -5
- package/dist/core/messages/en/github/index.js +0 -1
- package/dist/core/messages/ja/cli/cli-command-github-actions-messages.js +0 -5
- package/dist/core/messages/ja/github/index.js +0 -1
- package/dist/core/messages/pt/cli/cli-command-github-actions-messages.js +0 -5
- package/dist/core/messages/pt/github/index.js +0 -1
- package/dist/core/messages/zh/cli/cli-command-github-actions-messages.js +0 -5
- package/dist/core/messages/zh/github/index.js +0 -1
- package/dist/core/registry/file-registry.js +1 -1
- package/dist/node.loader.js +0 -2
- package/dist/reports/report-structure.js +2 -8
- package/dist/shared/formatters/formatters/commons.js +36 -10
- package/dist/shared/formatters/formatters/shell.js +6 -3
- package/dist/shared/helpers/magic-constants-whitelist.js +14 -1
- package/dist/types/analysts/index.js +1 -1
- package/dist/types/processing/filters.js +1 -4
- package/package.json +31 -32
- package/dist/app/github.js +0 -14
- package/dist/app/index.js +0 -1
- package/dist/core/messages/en/github/github-app-messages.js +0 -9
- package/dist/core/messages/ja/github/github-app-messages.js +0 -9
- package/dist/core/messages/pt/github/github-app-messages.js +0 -9
- 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`.*
|
|
File without changes
|