forjajs 5.0.1 → 5.1.0
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/CHANGELOG.md +38 -2
- package/README.md +4 -2
- package/README.pt-BR.md +4 -1
- package/boilerplates/02-saas-starter/README.md +58 -293
- package/boilerplates/02-saas-starter/backend/.env.example +13 -0
- package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
- package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
- package/boilerplates/02-saas-starter/backend/package.json +32 -73
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
- package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
- package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
- package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
- package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
- package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
- package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
- package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
- package/boilerplates/README.md +9 -10
- package/dist/bin/init-project.js +1 -0
- package/dist/lib/core/journey.js +10 -0
- package/dist/lib/generators/memory-generator.d.ts +0 -11
- package/dist/lib/generators/memory-generator.js +5 -161
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/llm/json-output.d.ts +14 -0
- package/dist/lib/llm/json-output.js +77 -0
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +74 -2
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/packages/llm/src/index.js +12 -2
- package/dist/scripts/llm-fit.js +23 -1
- package/docs/llm-fit-loop.md +16 -0
- package/memory/90-decisions/0088-templates-validados.md +3 -0
- package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
- package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
- package/package.json +1 -1
- package/specs/skills-do-projeto/plan.md +40 -0
- package/specs/skills-do-projeto/spec.md +63 -0
- package/specs/skills-do-projeto/tasks.md +27 -0
- package/templates/project/AGENTS.md +9 -0
- package/templates/project/agents/context-engineer.md +3 -0
- package/templates/project/agents/governance.md +3 -0
- package/templates/project/agents/marketing.md +3 -0
- package/templates/project/agents/orchestrator.md +3 -0
- package/templates/project/agents/product.md +3 -0
- package/templates/project/agents/sdd-architect.md +3 -0
- package/templates/project/skills/README.md +14 -0
- package/templates/project/skills/accessibility-review/SKILL.md +89 -0
- package/templates/project/skills/api-design/SKILL.md +77 -0
- package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
- package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
- package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
- package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
- package/templates/project/skills/commit-message/SKILL.md +143 -0
- package/templates/project/skills/data-migrations/SKILL.md +88 -0
- package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
- package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
- package/templates/project/skills/domain-modeling/SKILL.md +120 -0
- package/templates/project/skills/event-storming/SKILL.md +95 -0
- package/templates/project/skills/executive-writing/SKILL.md +99 -0
- package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
- package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
- package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
- package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
- package/templates/project/skills/observability/SKILL.md +93 -0
- package/templates/project/skills/product-evaluation/SKILL.md +130 -0
- package/templates/project/skills/prompt-spec/SKILL.md +83 -0
- package/templates/project/skills/pull-request/SKILL.md +101 -0
- package/templates/project/skills/query-performance/SKILL.md +83 -0
- package/templates/project/skills/release-checklist/SKILL.md +106 -0
- package/templates/project/skills/release-notes/SKILL.md +87 -0
- package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
- package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
- package/templates/project/skills/technical-spike/SKILL.md +101 -0
- package/templates/project/skills/testing/SKILL.md +109 -0
- package/templates/project/skills/threat-modeling/SKILL.md +87 -0
- package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
- package/templates/project/skills/ts-code-review/SKILL.md +121 -0
- package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
- package/templates/project/skills/ts-testing/SKILL.md +89 -0
- package/templates/project/skills/web-performance/SKILL.md +72 -0
- package/boilerplates/02-saas-starter/.env.example +0 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
- package/boilerplates/02-saas-starter/INFO.md +0 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
- package/boilerplates/02-saas-starter/START-HERE.md +0 -259
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: technical-spike
|
|
3
|
+
description: Use quando uma incerteza técnica é cara demais para assumir às cegas: planeja uma prova de conceito com tempo limitado, uma pergunta, critérios de sucesso e uma decisão, e registra o resultado.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Spike Técnico (Prova de Conceito)
|
|
7
|
+
|
|
8
|
+
Um spike é um experimento curto, com tempo limitado, que compra certeza antes de assumir algo caro. Seu produto é uma **decisão apoiada em evidência**, não código de produção.
|
|
9
|
+
|
|
10
|
+
Pagar alguns dias para descartar uma ideia ruim é um seguro contra gastar meses nela.
|
|
11
|
+
|
|
12
|
+
## Quando fazer
|
|
13
|
+
|
|
14
|
+
- Uma escolha técnica com alto custo de reversão que ninguém do time já fez (banco de dados novo, framework, integração, estilo de arquitetura).
|
|
15
|
+
- Uma dúvida de desempenho, escala ou viabilidade que a discussão não resolve.
|
|
16
|
+
- Várias opções concorrentes e o time continua debatendo em vez de decidir.
|
|
17
|
+
|
|
18
|
+
Não faça spike do que o time já sabe fazer. Faça.
|
|
19
|
+
|
|
20
|
+
## Regras
|
|
21
|
+
|
|
22
|
+
- **Uma pergunta por spike**, respondível com sim/não ou com a escolha entre opções.
|
|
23
|
+
- **Tempo fixo**: de 1–2 dias até uma semana no máximo. Quando acaba, o spike acaba, terminado ou não.
|
|
24
|
+
- **Critérios de sucesso e de fracasso definidos antes de começar.** Do contrário, o resultado é reinterpretado para caber no que foi construído.
|
|
25
|
+
- **Descartável por padrão**: um branch separado, nunca mesclado como está. O que for mantido é reescrito direito na linha principal, com testes.
|
|
26
|
+
- **Escopo mínimo**: só o necessário para responder à pergunta. Sem polimento de UI, sem tratamento de erro além do que a pergunta exige, sem generalização.
|
|
27
|
+
- **Evidência acima de impressão**: medições, um caminho funcionando, uma limitação reproduzida, código mostrando que a integração de fato funciona.
|
|
28
|
+
- **Um resultado inconclusivo é um resultado.** Registre o que se aprendeu e decida: descartar, ou fazer mais um spike com uma pergunta nova e mais estreita. Nunca estenda o tempo em silêncio.
|
|
29
|
+
|
|
30
|
+
## Processo
|
|
31
|
+
|
|
32
|
+
1. **Enquadre a pergunta.** O que exatamente precisa ser sabido para decidir? Que decisão depende disso?
|
|
33
|
+
2. **Defina os critérios.** Que resultado significa "adotar" e qual significa "descartar". Inclua limites mensuráveis quando fizer sentido (latência, vazão, memória, linhas de código de cola, tempo de setup).
|
|
34
|
+
3. **Defina o tempo e o escopo.** O que está dentro e o que está explicitamente fora.
|
|
35
|
+
4. **Execute.** Construa só o caminho crítico. Anote as surpresas na hora em que acontecem.
|
|
36
|
+
5. **Relate os achados** contra os critérios, com evidência.
|
|
37
|
+
6. **Decida**: adotar, descartar, ou um spike novo e mais estreito. Se adotado ou rejeitado e a decisão for relevante, registre-a como ADR (skill `architecture-decision-record`).
|
|
38
|
+
|
|
39
|
+
## Formato do plano
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
# Spike: <título curto>
|
|
43
|
+
|
|
44
|
+
- Pergunta: <a pergunta única>
|
|
45
|
+
- Decisão que destrava: <o que será decidido com a resposta>
|
|
46
|
+
- Tempo: <N dias, início–fim>
|
|
47
|
+
- Branch: spike/<slug>
|
|
48
|
+
|
|
49
|
+
## Hipótese
|
|
50
|
+
<O que esperamos encontrar.>
|
|
51
|
+
|
|
52
|
+
## Critérios de sucesso
|
|
53
|
+
- <condição mensurável ou observável>
|
|
54
|
+
|
|
55
|
+
## Critérios de fracasso
|
|
56
|
+
- <condição que significa descartar>
|
|
57
|
+
|
|
58
|
+
## Escopo
|
|
59
|
+
- Dentro: <...>
|
|
60
|
+
- Fora: <...>
|
|
61
|
+
|
|
62
|
+
## Riscos / suposições
|
|
63
|
+
- <...>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Formato do relatório
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
# Resultado do spike: <título curto>
|
|
70
|
+
|
|
71
|
+
- Resultado: <Adotar | Descartar | Inconclusivo → novo spike>
|
|
72
|
+
- Tempo gasto: <real vs. previsto>
|
|
73
|
+
|
|
74
|
+
## Achados
|
|
75
|
+
- <achado> — evidência: <medição, link, reprodução>
|
|
76
|
+
|
|
77
|
+
## Contra os critérios
|
|
78
|
+
| Critério | Resultado | Atendido? |
|
|
79
|
+
|
|
80
|
+
## Surpresas
|
|
81
|
+
- <o que não era esperado>
|
|
82
|
+
|
|
83
|
+
## Recomendação
|
|
84
|
+
<O que fazer em seguida. Se for adotar: o que precisa ser reconstruído direito e para que o código do spike não deve ser reaproveitado.>
|
|
85
|
+
|
|
86
|
+
## ADR
|
|
87
|
+
<NNNN, ou "não necessário" e por quê>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## No Forja
|
|
91
|
+
|
|
92
|
+
No Forja, o plano e o resultado do spike ficam em `memory/40-delivery/spikes/<slug>.md`; a decisão, quando relevante, vira ADR em `memory/90-decisions/` (`architecture-decision-record`). Rode `forja sync:universal` depois.
|
|
93
|
+
|
|
94
|
+
## Evite
|
|
95
|
+
|
|
96
|
+
- Spikes sem pergunta ("vamos brincar com X").
|
|
97
|
+
- Critérios definidos depois de ver os resultados.
|
|
98
|
+
- Mesclar código de spike no branch principal.
|
|
99
|
+
- Estender o tempo em vez de reformular a pergunta.
|
|
100
|
+
- Generalizar ou polir dentro do spike.
|
|
101
|
+
- Fazer várias perguntas num spike e não responder nenhuma com clareza.
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: testing
|
|
3
|
+
description: Use quando planejar ou escrever testes em qualquer linguagem: transforma critérios de aceite, invariantes de domínio, métodos derivados, transições de estado e políticas em casos de teste, segue os próprios idiomas de teste do código e impõe um fluxo de mudança seguro contra regressões.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Testes
|
|
7
|
+
|
|
8
|
+
Testes são um seguro contra regressão: o que funcionava ontem precisa continuar funcionando depois da mudança de hoje. Compilar não é evidência de correção, inclusive com tipos estáticos.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **plano de testes** (casos em Dado/Quando/Então). Escreva código de teste só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
Esta skill é agnóstica de linguagem: decide **o que** testar e **onde**. **Como** escrever segue os idiomas do código. Uma skill de linguagem (por exemplo, `ts-testing`) acrescenta os idiomas dessa linguagem; use as duas juntas.
|
|
13
|
+
|
|
14
|
+
## Convenções
|
|
15
|
+
|
|
16
|
+
- Termos de modelagem em pt-BR seguidos do en-US, como na skill `domain-modeling`.
|
|
17
|
+
- Nomes dos casos na linguagem ubíqua do usuário.
|
|
18
|
+
- Entradas: critérios de aceite de `requirements-gathering`, o modelo de `domain-modeling`.
|
|
19
|
+
|
|
20
|
+
## Siga o código existente
|
|
21
|
+
|
|
22
|
+
Antes de planejar ou escrever testes, leia os que já existem. Acompanhe:
|
|
23
|
+
|
|
24
|
+
- O framework de testes, o executor e o estilo de asserção já usados. Não introduza outro.
|
|
25
|
+
- Localização e nomes dos arquivos (`foo.test.ts`, `foo.spec.ts`, `foo_test.go`, `test_foo.py`, `FooTest.java`, pasta `tests/`…).
|
|
26
|
+
- Como fakes, fixtures e dados de teste são construídos.
|
|
27
|
+
- Como os testes de integração ficam separados da suíte rápida (tags, marcadores, pastas, comandos separados).
|
|
28
|
+
- Os comandos que o CI executa.
|
|
29
|
+
|
|
30
|
+
Quando o código ainda não tem testes, use as ferramentas padrão da linguagem e suas convenções mais comuns, com o mínimo de dependências.
|
|
31
|
+
|
|
32
|
+
## Fluxo de mudança
|
|
33
|
+
|
|
34
|
+
Aplique a toda mudança, antes de discutir técnica:
|
|
35
|
+
|
|
36
|
+
1. **Correção de bug**: escreva um teste que reproduza o bug e falhe. Corrija. O teste passa e fica como proteção.
|
|
37
|
+
2. **Funcionalidade nova**: os testes vão na mesma mudança. Sem testes, não está pronto.
|
|
38
|
+
3. **Código legado sem testes**: não planeje uma campanha de cobertura. Cubra o que você está mexendo agora, um teste por vez.
|
|
39
|
+
4. **Percentual de cobertura não é meta.** Cubra regras, limites e bugs passados; pule trivialidades.
|
|
40
|
+
5. **Atualização de dependência ou de runtime**: rode a suíte inteira antes de mesclar.
|
|
41
|
+
6. **Incerteza sobre uma abordagem**: escreva o teste primeiro. É a prova de conceito mais barata.
|
|
42
|
+
|
|
43
|
+
O CI roda a suíte inteira. Localmente, rode só os módulos que você está mexendo.
|
|
44
|
+
|
|
45
|
+
## O que testar, por camada
|
|
46
|
+
|
|
47
|
+
| Camada | Tipo de teste | Dependências |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| Domínio (objetos de valor, entidades, agregados, políticas) | Testes unitários puros. É aqui que mora a maior parte dos testes. | Nenhuma. Sem mocks. |
|
|
50
|
+
| Aplicação (casos de uso, serviços de domínio) | Testes unitários de orquestração e de regras entre agregados. | Fakes em memória escritos à mão, implementando as interfaces de repositório. |
|
|
51
|
+
| Infraestrutura (repositórios, filas, clientes externos) | Testes de integração contra dependências reais (por exemplo, o banco real num container). | Serviços reais, isolados por teste. |
|
|
52
|
+
| HTTP/transporte | Testes de handler: códigos de status, contrato do payload, mapeamento de erros. | Casos de uso substituídos por fakes. |
|
|
53
|
+
|
|
54
|
+
Prefira fakes a mocks: um fake verifica o resultado; um mock verifica a sequência de chamadas e quebra a cada refatoração.
|
|
55
|
+
|
|
56
|
+
## Do modelo de domínio aos casos de teste
|
|
57
|
+
|
|
58
|
+
Quando existe um modelo de `domain-modeling`, derive os casos de forma mecânica:
|
|
59
|
+
|
|
60
|
+
- **Construtor de objeto de valor**: um caso de aceitação por formato válido. Um caso de rejeição por invariante. Limites dos dois lados (por exemplo, fim == início aceito, fim um milissegundo antes do início rejeitado).
|
|
61
|
+
- **Invariante**: pelo menos um caso que tente quebrá-la por cada caminho público que poderia quebrá-la, e um caso exatamente no limite.
|
|
62
|
+
- **Método derivado**: valor típico, valor zero/vazio e limite (por exemplo, a duração de um período instantâneo é zero; `contains` no início e no fim).
|
|
63
|
+
- **Comportamento / transição de estado**: uma tabela de transições. Toda transição válida tem sucesso e muda o estado. Toda transição inválida, a partir de cada estado, devolve erro e deixa o agregado inalterado.
|
|
64
|
+
- **Política**: limites dos parâmetros. Logo abaixo do limite, exatamente nele e logo acima. Se a política é configurável, teste com pelo menos duas configurações.
|
|
65
|
+
- **Regra entre agregados**: teste na camada de aplicação usando fakes.
|
|
66
|
+
- **Evento de domínio**: verifique que ele é emitido exatamente quando o fato acontece, e não em operações rejeitadas.
|
|
67
|
+
- **Critério de aceite**: cada Dado/Quando/Então de `requirements-gathering` vira pelo menos um caso na camada onde o comportamento mora.
|
|
68
|
+
- **Suposições e perguntas em aberto**: sem testes. Liste-as como pendentes até o negócio confirmá-las.
|
|
69
|
+
|
|
70
|
+
## Práticas
|
|
71
|
+
|
|
72
|
+
- Um teste por comportamento, nomeado pelo comportamento. Agrupe casos do mesmo comportamento (tabelas, testes parametrizados).
|
|
73
|
+
- Teste a API pública. Alcance o interno só quando não houver caminho público.
|
|
74
|
+
- **Determinismo**: tempo, IDs e aleatoriedade são injetados, nunca lidos de globais dentro do domínio.
|
|
75
|
+
- Verifique tipos ou categorias de erro, nunca o texto da mensagem.
|
|
76
|
+
- Fixtures em arquivos para entradas grandes; golden files para saídas grandes, com um jeito de regenerá-los.
|
|
77
|
+
- Testes baseados em propriedades ou fuzzing para parsers e construtores de objetos de valor que aceitam entrada externa (CPF/CNPJ, e-mails, documentos).
|
|
78
|
+
- Testes de integração separados da suíte rápida, para que ela continue rápida. Cada teste é dono dos seus dados: uma transação revertida no fim, ou um schema dedicado.
|
|
79
|
+
- Benchmarks só quando desempenho é um requisito declarado.
|
|
80
|
+
|
|
81
|
+
## Formato do plano
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
## <Elemento> (<Objeto de Valor | Agregado | Política | Caso de uso>)
|
|
85
|
+
|
|
86
|
+
| Caso | Dado | Quando | Então |
|
|
87
|
+
|---|---|---|---|
|
|
88
|
+
| <nome na linguagem ubíqua> | <estado/entrada> | <ação> | <resultado ou erro esperado> |
|
|
89
|
+
|
|
90
|
+
Camada: <domínio | aplicação | infraestrutura | transporte>
|
|
91
|
+
Dependências: <nenhuma | fakes: X, Y | reais: <banco, fila…>>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Feche com **Pendentes**: regras que dependem de suposições não confirmadas e por isso ainda não têm testes.
|
|
95
|
+
|
|
96
|
+
## No Forja
|
|
97
|
+
|
|
98
|
+
No Forja, os critérios de aceite estão em `specs/<slug>/spec.md` (§4, `AC-n`). Nomeie os casos citando o `AC-n` que cobrem, para a ligação spec → teste ficar rastreável, e registre a evidência na seção "Evidências e estado real" da spec.
|
|
99
|
+
|
|
100
|
+
## Evite
|
|
101
|
+
|
|
102
|
+
- Testar getters, construtores triviais, código gerado ou o próprio framework.
|
|
103
|
+
- Chamar funções privadas diretamente para atingir cobertura.
|
|
104
|
+
- Mocks que verificam a ordem das chamadas em vez dos resultados.
|
|
105
|
+
- Testes que dependem da ordem de execução, do relógio real ou de dados compartilhados.
|
|
106
|
+
- Um teste gigante cobrindo vários comportamentos.
|
|
107
|
+
- Introduzir um framework ou estilo de teste que o código não usa.
|
|
108
|
+
- Pular testes para cumprir prazo. Corte escopo.
|
|
109
|
+
- Gerar código de teste sem que peçam.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: threat-modeling
|
|
3
|
+
description: Use quando desenhar ou alterar um sistema, funcionalidade ou API que atravessa uma fronteira de confiança: mapeia os fluxos de dados, encontra ameaças com STRIDE, avalia o risco e transforma as mitigações em requisitos e casos de teste.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Modelagem de Ameaças
|
|
7
|
+
|
|
8
|
+
Faz quatro perguntas, nesta ordem: o que estamos construindo, o que pode dar errado, o que vamos fazer a respeito e se fizemos um bom trabalho. É feita na fase de design, quando uma mitigação custa uma linha numa especificação em vez de uma reescrita.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **tabela de ameaças com mitigações**. É uma revisão de design, não um teste de invasão; termina com o que ainda precisa de verificação.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: atores e `RF-NN` / `RNF-NN` de `requirements-gathering`; endpoints e regras de autorização de `api-design`; classificação de dados de `lgpd-compliance`; ADRs de arquitetura.
|
|
15
|
+
- As mitigações viram requisitos (`RNF-NN`, IDs novos só via `requirements-gathering`) e casos de teste para `testing`.
|
|
16
|
+
- Escopo: uma funcionalidade ou mudança por vez. Um modelo do sistema inteiro só na primeira passada ou num redesenho grande.
|
|
17
|
+
- Não invente capacidades de atacantes nem incidentes. Incógnitas (hospedagem, exposição de rede, garantias de terceiros) vão para **Perguntas em aberto**.
|
|
18
|
+
|
|
19
|
+
## Processo
|
|
20
|
+
|
|
21
|
+
### 1. Modelar o sistema
|
|
22
|
+
Desenhe um diagrama de fluxo de dados (Mermaid ou uma lista) com:
|
|
23
|
+
- **Entidades externas**: usuários, administradores, sistemas de terceiros.
|
|
24
|
+
- **Processos**: serviços, jobs, funções.
|
|
25
|
+
- **Armazenamentos de dados**: bancos, caches, filas, buckets, logs.
|
|
26
|
+
- **Fluxos de dados** entre eles, rotulados com o que trafega (credenciais, dados pessoais, pagamentos).
|
|
27
|
+
- **Fronteiras de confiança**: onde o privilégio ou a propriedade muda (internet → API, API → banco, seu sistema → fornecedor).
|
|
28
|
+
|
|
29
|
+
As ameaças moram onde os fluxos cruzam fronteiras. Marque esses fluxos.
|
|
30
|
+
|
|
31
|
+
### 2. Encontrar ameaças com STRIDE
|
|
32
|
+
|
|
33
|
+
| Ameaça | Viola | Pergunta | Mitigação típica |
|
|
34
|
+
|---|---|---|---|
|
|
35
|
+
| **S**poofing (falsificação de identidade) | Autenticação | Alguém consegue se passar por outro usuário ou serviço? | Autenticação forte, MFA, mTLS, tokens assinados com expiração curta |
|
|
36
|
+
| **T**ampering (adulteração) | Integridade | Os dados podem ser alterados em trânsito ou em repouso? | TLS, validação de entrada, assinaturas, constraints, escrita com privilégio mínimo |
|
|
37
|
+
| **R**epudiation (repúdio) | Não repúdio | Alguém pode negar uma ação que não conseguimos provar? | Log de auditoria com ator, horário e objeto, somente acréscimo |
|
|
38
|
+
| **I**nformation disclosure (vazamento de informação) | Confidencialidade | Os dados podem chegar a quem não deveria vê-los? | Autorização no nível do objeto, criptografia, respostas mínimas, nada de segredos ou dados pessoais nos logs |
|
|
39
|
+
| **D**enial of service (negação de serviço) | Disponibilidade | Alguém consegue esgotar um recurso? | Limites de taxa e de tamanho, timeouts, cotas, limites de paginação |
|
|
40
|
+
| **E**levation of privilege (elevação de privilégio) | Autorização | Alguém consegue obter direitos que não deveria ter? | Verificações no servidor a cada requisição, negar por padrão, nada de atribuição em massa |
|
|
41
|
+
|
|
42
|
+
Aplique por elemento: entidades externas (S, R), processos (os seis), armazenamentos (T, I, D, e R para logs), fluxos de dados (T, I, D). Verifique também os suspeitos de sempre: autorização quebrada no nível do objeto (IDOR), injeção, SSRF, segredos no código ou nos logs, vulnerabilidades de dependências e padrões inseguros.
|
|
43
|
+
|
|
44
|
+
### 3. Avaliar o risco
|
|
45
|
+
Probabilidade (baixa/média/alta) × impacto (baixo/médio/alto), com uma linha de justificativa. O impacto sobre dados pessoais segue `lgpd-compliance` (dados sensíveis elevam o impacto).
|
|
46
|
+
|
|
47
|
+
### 4. Decidir
|
|
48
|
+
Por ameaça: **mitigar**, **eliminar** (remover a funcionalidade ou o dado), **transferir** (para um fornecedor, com o contrato declarado) ou **aceitar**. Um risco aceito precisa de um dono e de uma data de revisão, e pode merecer um ADR.
|
|
49
|
+
|
|
50
|
+
### 5. Validar
|
|
51
|
+
Cada mitigação tem uma verificação: um caso de teste, uma checagem de configuração ou um item de revisão. Uma mitigação sem verificação é uma esperança.
|
|
52
|
+
|
|
53
|
+
## Formato
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
## Escopo
|
|
57
|
+
<funcionalidade/mudança, em um parágrafo; o que está fora do escopo>
|
|
58
|
+
|
|
59
|
+
## Diagrama de fluxo de dados
|
|
60
|
+
<mermaid ou lista; fronteiras de confiança marcadas>
|
|
61
|
+
|
|
62
|
+
## Ameaças
|
|
63
|
+
| ID | Elemento / fluxo | STRIDE | Ameaça | Probabilidade | Impacto | Decisão | Mitigação | Verificação |
|
|
64
|
+
|---|---|---|---|---|---|---|---|---|
|
|
65
|
+
| T-01 | Internet → API: GET /orders/{id} | I | Usuário lê o pedido de outro trocando o ID | Alta | Alto | Mitigar | Verificação de dono no nível do objeto | Teste: ID de outro usuário devolve 404 |
|
|
66
|
+
|
|
67
|
+
## Riscos aceitos
|
|
68
|
+
| ID | Dono | Motivo | Revisar em |
|
|
69
|
+
|
|
70
|
+
## Perguntas em aberto
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Próximo
|
|
74
|
+
|
|
75
|
+
- `requirements-gathering` registra as mitigações como `RNF-NN`.
|
|
76
|
+
- `testing` recebe um caso por verificação.
|
|
77
|
+
- `observability` registra e alerta sobre os ataques que você mitigou (falhas de autenticação, acionamentos do limite de taxa).
|
|
78
|
+
- `architecture-decision-record` para riscos aceitos e escolhas de arquitetura de segurança.
|
|
79
|
+
|
|
80
|
+
## Evite
|
|
81
|
+
|
|
82
|
+
- Listar ameaças genéricas sem ligá-las a um elemento deste sistema.
|
|
83
|
+
- Mitigações sem verificação.
|
|
84
|
+
- Tratar verificações do lado do cliente como segurança.
|
|
85
|
+
- Aceitar risco sem um dono.
|
|
86
|
+
- Avaliar tudo como alto. Se tudo é crítico, nada é priorizado.
|
|
87
|
+
- Recomendar uma ferramenta ou produto como mitigação em vez do controle que ele oferece.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ts-async-patterns
|
|
3
|
+
description: Use quando código TypeScript ou JavaScript precisa de concorrência ou tem bugs assíncronos (serviços Node, workers, scripts): decide se a concorrência é necessária e então orienta a posse das promises, cancelamento e timeouts com AbortSignal, concorrência limitada, backpressure de streams, worker threads para trabalho de CPU e desligamento limpo, com um checklist de vazamentos.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Padrões Assíncronos em TypeScript
|
|
7
|
+
|
|
8
|
+
O Node roda seu código numa thread só e faz I/O de forma concorrente. Isso torna a concorrência fácil de começar e fácil de errar: um `Promise.all` sobre dez mil itens abre dez mil conexões, uma promise esquecida rejeita sem ninguém ouvindo, e um `setInterval` mantém o processo vivo depois do desligamento. Toda operação assíncrona precisa de um dono que a aguarde e de uma forma de pará-la.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **escolha de padrão com a justificativa e um checklist**. Escreva código só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: metas de vazão e latência de `requirements-gathering` / `observability`, limites de taxa dos serviços a jusante, o código existente.
|
|
15
|
+
- Os padrões já existentes no código prevalecem. APIs da plataforma primeiro (`AbortController`, `node:stream/promises`, `node:timers/promises`, `node:worker_threads`), depois bibliotecas pequenas e focadas (`p-limit`, `p-map`, `piscina`) quando o projeto permite dependências.
|
|
16
|
+
- Promises soltas são pegas pelo linter (`@typescript-eslint/no-floating-promises` ou o `typescript/no-floating-promises` do oxlint); veja `ts-code-review`.
|
|
17
|
+
|
|
18
|
+
## Decida primeiro
|
|
19
|
+
|
|
20
|
+
A concorrência se justifica quando o trabalho é **independente** e limitado por I/O (chamadas, consultas, arquivos). Trabalho limitado por CPU não fica mais rápido com mais promises: ele bloqueia o event loop e precisa de worker threads ou de outro processo. "Deixar mais rápido" sem uma medição não é motivo. `for … of` sequencial com `await` é o padrão.
|
|
21
|
+
|
|
22
|
+
## Regras
|
|
23
|
+
|
|
24
|
+
- **Posse**: a função que inicia o trabalho assíncrono o aguarda ou o entrega a alguém que aguarda. Nada de "dispara e esquece" em caminhos de requisição. Uma tarefa de fundo deliberada passa por uma fila ou por um supervisor que registra e tenta de novo.
|
|
25
|
+
- **Cancelamento**: toda operação longa ou de saída aceita um `AbortSignal` e o repassa (`fetch(url, { signal })`, drivers de banco, `setTimeout` de `node:timers/promises`). Combine sinais com `AbortSignal.any([pai, AbortSignal.timeout(ms)])`.
|
|
26
|
+
- **Prazos**: toda chamada de saída tem um timeout derivado do orçamento de quem chama. `fetch` não tem timeout padrão.
|
|
27
|
+
- **Concorrência limitada**: nunca `Promise.all(items.map(fn))` sobre uma entrada sem limite. Use um limite (`p-limit`, `p-map` com `concurrency`, ou um pequeno pool de workers).
|
|
28
|
+
- **Erros**: toda promise tem um tratamento. Escolha de propósito entre `Promise.all` (falha rápido; as outras continuam rodando, a menos que você as aborte) e `Promise.allSettled` (coleta todos os resultados). Uma rejeição sem tratamento derruba o processo Node por padrão; isso está certo, então não a silencie globalmente.
|
|
29
|
+
- **Estado compartilhado**: o event loop torna atômicas as instruções isoladas, não as sequências que atravessam um `await`. Um ler-alterar-escrever que atravessa um `await` precisa de um lock, uma fila ou uma transação.
|
|
30
|
+
- **Recursos**: libere em `finally` ou com `await using` (gerenciamento explícito de recursos) para conexões, handles de arquivo e locks. Remova os listeners e limpe os timers que você criou.
|
|
31
|
+
- **Nunca bloqueie o loop**: nada de criptografia ou compressão síncrona, `JSON.parse` grande ou APIs de arquivo `*Sync` em caminhos de requisição.
|
|
32
|
+
|
|
33
|
+
## Padrões
|
|
34
|
+
|
|
35
|
+
| Necessidade | Padrão |
|
|
36
|
+
|---|---|
|
|
37
|
+
| Rodar N tarefas independentes, falhar rápido no primeiro erro | `Promise.all` com limite, mais um `AbortController` abortado na primeira falha |
|
|
38
|
+
| Rodar N tarefas e reportar todos os resultados | `Promise.allSettled` com limite; mapeie os resultados por índice |
|
|
39
|
+
| Processar um fluxo de jobs com paralelismo fixo | Pool de workers limitado (`p-limit` / `p-map`) ou uma fila com N consumidores |
|
|
40
|
+
| Transformar dados em etapas | `node:stream` + `pipeline()` de `node:stream/promises`, ou geradores assíncronos consumidos com `for await` |
|
|
41
|
+
| Chamar vários backends e juntar os resultados | Fan-out com limite e `AbortSignal.timeout` por chamada; colete num array indexado pela posição |
|
|
42
|
+
| Trabalho limitado por CPU | `worker_threads` (um pool como `piscina`), nunca na thread principal |
|
|
43
|
+
| Limitar a taxa de chamadas a uma dependência | Token bucket ou o limitador do provedor; respeite `Retry-After` |
|
|
44
|
+
| Evitar trabalho concorrente duplicado | Memorize a promise em andamento por chave (single-flight) e limpe-a ao concluir |
|
|
45
|
+
| Tentar de novo uma falha transitória | Backoff exponencial com jitter e um número máximo de tentativas, só para operações idempotentes |
|
|
46
|
+
|
|
47
|
+
## Backpressure
|
|
48
|
+
|
|
49
|
+
Quando os produtores são mais rápidos que os consumidores, escolha de propósito:
|
|
50
|
+
|
|
51
|
+
- **Bloquear**: respeite o `write()` devolvendo `false` e espere o `'drain'`, ou use `pipeline()`, que faz isso por você. Padrão para pipelines internos.
|
|
52
|
+
- **Rejeitar**: devolva `429`/`503` quando a fila estiver cheia. Para serviços guiados por requisições.
|
|
53
|
+
- **Descartar ou amostrar**: para dados do tipo telemetria, em que a perda é aceitável. Conte os descartes como métrica.
|
|
54
|
+
|
|
55
|
+
Nunca use um array sem limite como fila: ele transforma sobrecarga em estouro de heap.
|
|
56
|
+
|
|
57
|
+
## Desligamento limpo
|
|
58
|
+
|
|
59
|
+
Em `SIGTERM`/`SIGINT`: pare de aceitar trabalho (`server.close()`, depois `server.closeIdleConnections()`), aborte o `AbortController` raiz, espere o trabalho em andamento com um prazo, descarregue e feche os recursos (pool do banco, consumidores de fila, telemetria) e então saia. Registre os handlers uma vez, na raiz de composição. Os frameworks oferecem ganchos para isso (`app.enableShutdownHooks()` no NestJS, `onClose` no Fastify).
|
|
60
|
+
|
|
61
|
+
## Checklist
|
|
62
|
+
|
|
63
|
+
- [ ] Toda promise é aguardada, devolvida ou explicitamente possuída por um supervisor.
|
|
64
|
+
- [ ] Toda operação longa ou de saída recebe um `AbortSignal` e tem timeout.
|
|
65
|
+
- [ ] A concorrência sobre coleções é limitada.
|
|
66
|
+
- [ ] Grupos que falham rápido abortam o trabalho restante no primeiro erro.
|
|
67
|
+
- [ ] Nenhum ler-alterar-escrever de estado compartilhado atravessa um `await` sem lock ou transação.
|
|
68
|
+
- [ ] Nenhum trabalho pesado de CPU ou `*Sync` no event loop em caminhos de requisição.
|
|
69
|
+
- [ ] Listeners, intervals e timers criados são removidos no desligamento.
|
|
70
|
+
- [ ] O desligamento escoa o trabalho em andamento dentro de um prazo.
|
|
71
|
+
- [ ] Os testes usam timers falsos (`vi.useFakeTimers()`, `mock.timers` no `node:test`) ou relógios injetados em vez de esperas reais.
|
|
72
|
+
|
|
73
|
+
## Formato
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
## Problema
|
|
77
|
+
<carga, tamanho da entrada, metas, limitado por I/O ou por CPU>
|
|
78
|
+
|
|
79
|
+
## Decisão
|
|
80
|
+
<sequencial | padrão>, porque <motivo>. Limite: <n>, a partir de <medição ou limite a jusante>.
|
|
81
|
+
Cancelamento/timeouts: <sinais e orçamentos>. Backpressure: <bloquear | rejeitar | descartar>. Desligamento: <sequência>.
|
|
82
|
+
|
|
83
|
+
## Checklist
|
|
84
|
+
<itens com ✅/❌ para o código existente>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Próximo
|
|
88
|
+
|
|
89
|
+
- `ts-testing` para testes com timers falsos e de caminhos de aborto.
|
|
90
|
+
- `ts-code-review` verifica o checklist na implementação.
|
|
91
|
+
- `observability`: atraso do event loop, profundidade da fila, quantidade em andamento e descartes como métricas.
|
|
92
|
+
|
|
93
|
+
## Evite
|
|
94
|
+
|
|
95
|
+
- `Promise.all` sobre entrada sem limite.
|
|
96
|
+
- Callbacks `async` passados ao `forEach` (ninguém os aguarda).
|
|
97
|
+
- Promises iniciadas e nunca aguardadas em caminhos de requisição.
|
|
98
|
+
- Esperas baseadas em `setTimeout` para sincronização.
|
|
99
|
+
- Engolir erros com `.catch(() => {})`, ou um handler global de `unhandledRejection` que só registra.
|
|
100
|
+
- Trabalho limitado por CPU na thread principal.
|
|
101
|
+
- Adicionar concorrência sem uma medição mostrando que ajuda.
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ts-code-review
|
|
3
|
+
description: Use quando revisar código TypeScript ou JavaScript, ou um diff de TS/JS: roda a checagem de tipos, o linter e os testes, depois verifica segurança de tipos, tratamento de erros, correção assíncrona e vazamentos, acoplamento entre módulos, validação de entrada nas fronteiras, uso de recursos e testes, e reporta os achados ordenados por severidade.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Revisão de Código TypeScript
|
|
7
|
+
|
|
8
|
+
Procura o que torna o código TypeScript errado, frágil ou difícil de mudar, nesta ordem. O estilo que o formatador e o linter já garantem não é assunto de revisão. Tipos são evidência de forma, não de correção: um `tsc` verde com `any` e `as` por toda parte prova pouco.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **tabela de achados**. Edite o código só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Escopo: o diff contra o branch base (`git diff <base>...HEAD -- '*.ts' '*.tsx' '*.js' '*.mjs'`) ou os módulos que o usuário nomear. Leia o código ao redor o suficiente para julgar, mas revise só o escopo.
|
|
15
|
+
- Referências: `ts-module-layout` (regras de dependência), `ts-async-patterns` (checklist), `ts-testing` (idiomas de teste), `domain-modeling` (invariantes).
|
|
16
|
+
- As convenções do código prevalecem sobre conselhos gerais, a menos que causem um bug.
|
|
17
|
+
- Todo achado cita `arquivo:linha` e explica **por que** importa. Nenhum achado sem um motivo concreto.
|
|
18
|
+
|
|
19
|
+
## Rode primeiro
|
|
20
|
+
|
|
21
|
+
Quando o toolchain estiver disponível, com os próprios scripts do projeto:
|
|
22
|
+
|
|
23
|
+
1. Checagem de tipos: `tsc --noEmit` (ou `tsc -b`). Observe as flags `strict` do `tsconfig.json`; `strict: false` em código novo já é um achado.
|
|
24
|
+
2. Lint: o linter do projeto (`eslint` com as regras type-aware do `typescript-eslint`, `oxlint --type-aware` ou `biome check`).
|
|
25
|
+
3. Testes dos módulos afetados, e o build se a mudança mexer em configuração ou nos exports.
|
|
26
|
+
4. Quando fizer sentido: `npx madge --circular` (ciclos novos), `npx knip` (exports ou dependências novas sem uso), `npm audit`/`osv-scanner` para dependências novas.
|
|
27
|
+
|
|
28
|
+
Reporte as falhas deles como achados. Não repita com suas palavras o que eles já dizem.
|
|
29
|
+
|
|
30
|
+
## Checklist
|
|
31
|
+
|
|
32
|
+
**Segurança de tipos**
|
|
33
|
+
- `any` (explícito ou implícito) onde um tipo real ou `unknown` + estreitamento funcionaria.
|
|
34
|
+
- Casts com `as` que afirmam em vez de verificar, principalmente sobre dados externos; casts duplos (`as unknown as T`).
|
|
35
|
+
- Asserções de não nulo (`!`) sem um motivo para o valor não poder ser nulo.
|
|
36
|
+
- `@ts-ignore` em vez de `@ts-expect-error` com explicação; supressões escondendo um erro real.
|
|
37
|
+
- Exaustividade: `switch` sobre uma união sem a checagem `never` no `default`.
|
|
38
|
+
- Acesso por índice em arrays e records tratado como sempre definido (com `noUncheckedIndexedAccess` desligado).
|
|
39
|
+
|
|
40
|
+
**Fronteiras e validação**
|
|
41
|
+
- Entrada externa (corpos HTTP, query params, variáveis de ambiente, mensagens de fila, `JSON.parse`, respostas de terceiros) validada na fronteira com um schema (`zod`, `valibot`, class-validator no Nest), e não confiada por meio de uma anotação de tipo.
|
|
42
|
+
- Invariantes que podem ser contornadas: campos públicos mutáveis num agregado, construtores ou fábricas que pulam a validação, objetos devolvidos por referência e alterados por quem chama.
|
|
43
|
+
- Dinheiro como ponto flutuante; datas tratadas sem um fuso horário explícito; IDs comparados entre tipos diferentes.
|
|
44
|
+
|
|
45
|
+
**Erros**
|
|
46
|
+
- Valores lançados que não são instâncias de `Error`; erros sem `cause` ao encapsular (`new Error('carregar pedido', { cause: err })`).
|
|
47
|
+
- `catch (e)` que assume que `e` é um `Error` sem estreitar.
|
|
48
|
+
- Erros engolidos (`catch {}` sem comentário), ou registrados **e** relançados (tratados duas vezes).
|
|
49
|
+
- Falhas de domínio esperadas modeladas como `Error` genérico, de modo que quem chama não consegue decidir por elas.
|
|
50
|
+
- `return promise` dentro de `try` sem `await`, de modo que o `catch`/`finally` nunca vê a rejeição.
|
|
51
|
+
|
|
52
|
+
**Assíncrono** (veja `ts-async-patterns`)
|
|
53
|
+
- Promises soltas; callbacks `async` em `forEach`/`map` cujos resultados ninguém aguarda.
|
|
54
|
+
- `Promise.all` sem limite sobre coleções de entrada.
|
|
55
|
+
- `AbortSignal` ou timeout ausentes em chamadas de saída; `fetch` sem prazo.
|
|
56
|
+
- Ler-alterar-escrever de estado compartilhado atravessando um `await`.
|
|
57
|
+
- Timers, intervals e listeners nunca limpos; trabalho síncrono ou pesado de CPU no event loop.
|
|
58
|
+
|
|
59
|
+
**Design e acoplamento** (veja `ts-module-layout`)
|
|
60
|
+
- Código de domínio importando o ORM, o framework HTTP, SDKs ou `process.env`.
|
|
61
|
+
- Barrel files novos, pastas genéricas (`utils/`, `common/`) ganhando código, ciclos de import novos.
|
|
62
|
+
- Interfaces declaradas ao lado da sua única implementação "para mockar".
|
|
63
|
+
- Exports que não precisam ser exportados; default exports onde o código usa exports nomeados.
|
|
64
|
+
- Decorators de framework (Nest, TypeORM) vazando para os tipos de domínio.
|
|
65
|
+
|
|
66
|
+
**Idiomas**
|
|
67
|
+
- Uniões de tipos ou objetos `as const` vs. `enum`: siga o código; sinalize a mistura de estilos no mesmo módulo.
|
|
68
|
+
- `interface` vs. `type`: siga o código.
|
|
69
|
+
- `==` em vez de `===`; checagens de "verdadeiro" que falham com `0` ou `''`.
|
|
70
|
+
- Mutação de parâmetros de função; estado mutável compartilhado no nível do módulo.
|
|
71
|
+
- ESM e CommonJS misturados no mesmo pacote; imports ESM relativos sem `.js` com `nodenext`.
|
|
72
|
+
|
|
73
|
+
**Recursos e desempenho**
|
|
74
|
+
- Conexões, handles de arquivo e streams não liberados em `finally` ou com `await using`.
|
|
75
|
+
- Consultas N+1 em laços (veja `query-performance`), conjuntos de resultado sem limite e sem paginação.
|
|
76
|
+
- `JSON.parse`/`readFileSync` grandes e síncronos em caminhos de requisição; trabalho quadrático acidental (`array.includes` dentro de um laço sobre o mesmo array).
|
|
77
|
+
- Front-end: re-renderizações desnecessárias por props instáveis, effects sem limpeza, arrays de dependência faltando.
|
|
78
|
+
|
|
79
|
+
**Testes** (veja `ts-testing`)
|
|
80
|
+
- A mudança tem testes; uma correção de bug tem um teste que o reproduz.
|
|
81
|
+
- Nada de esperas reais, de dependência de ordem, de asserções sobre texto de erro, de `rejects` sem `await`.
|
|
82
|
+
|
|
83
|
+
## Severidade
|
|
84
|
+
|
|
85
|
+
| Nível | Significado |
|
|
86
|
+
|---|---|
|
|
87
|
+
| Bloqueador | Bug, perda de dados, entrada externa sem validação, rejeição sem tratamento, vazamento, problema de segurança. Precisa ser corrigido antes do merge. |
|
|
88
|
+
| Maior | Quebra uma regra de design, enfraquece a segurança de tipos numa fronteira ou torna a próxima mudança arriscada. Deve ser corrigido agora. |
|
|
89
|
+
| Menor | Clareza ou idioma; corrija se for barato. |
|
|
90
|
+
| Detalhe | Preferência. Opcional; mantenha poucos. |
|
|
91
|
+
|
|
92
|
+
## Formato
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
## Resumo
|
|
96
|
+
<um parágrafo: avaliação geral, quantidade de bloqueadores>
|
|
97
|
+
|
|
98
|
+
## Resultado das ferramentas
|
|
99
|
+
<tsc / lint / testes / ciclos: passou ou falhas>
|
|
100
|
+
|
|
101
|
+
## Achados
|
|
102
|
+
| # | Arquivo:linha | Severidade | Problema | Por que importa | Correção sugerida |
|
|
103
|
+
|---|---|---|---|---|---|
|
|
104
|
+
|
|
105
|
+
## O que está bom
|
|
106
|
+
<uma ou duas coisas que vale manter>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## No Forja
|
|
110
|
+
|
|
111
|
+
No Forja, antes de revisar, rode `forja code:check` e, para os símbolos alterados, `forja code:impact <símbolo>` (chamadores e raio de impacto); sem o codegraph, busque os chamadores com `rg`. Mudança estrutural sem ADR é um achado Maior.
|
|
112
|
+
|
|
113
|
+
## Evite
|
|
114
|
+
|
|
115
|
+
- Comentários de formatação que o formatador resolve.
|
|
116
|
+
- Achados sem `arquivo:linha` ou sem motivo.
|
|
117
|
+
- Esconder bloqueadores no meio dos detalhes.
|
|
118
|
+
- Pedir mais tipos onde o tipo inferido já é exato.
|
|
119
|
+
- Sugerir uma reescrita quando uma correção local resolve.
|
|
120
|
+
- Revisar código fora do escopo pedido.
|
|
121
|
+
- Afirmar que as ferramentas passaram sem rodá-las.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ts-module-layout
|
|
3
|
+
description: Use quando organizar ou reorganizar uma base de código TypeScript ou JavaScript (serviços Node, NestJS, bibliotecas, front-ends): avalia a árvore de pastas e o grafo de imports atuais e propõe uma estrutura alinhada aos contextos delimitados, sem ciclos de import, barrel files ou pastas genéricas, com regras de dependência verificáveis e um plano de movimentação incremental.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Estrutura de Módulos em TypeScript
|
|
7
|
+
|
|
8
|
+
Em TypeScript o arquivo é o módulo, e a pasta é só uma convenção. Nada impede um arquivo de domínio de importar o cliente do banco, a não ser regras que você escreve e verifica. Uma estrutura organizada por contexto de negócio mantém uma mudança num lugar só. Uma estrutura organizada por camada técnica (`models/`, `services/`, `controllers/`) espalha cada funcionalidade pela árvore inteira, e os barrel files (`index.ts` que reexportam tudo) a transformam numa teia de ciclos.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **avaliação e uma estrutura alvo com um plano de movimentação**. Mova arquivos só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: contextos de `bounded-context-mapping` ou `domain-modeling`; a árvore atual; `package.json`, `tsconfig.json` e o framework em uso.
|
|
15
|
+
- As convenções existentes prevalecem quando funcionam. Proponha uma mudança só para um problema concreto (ciclos, acoplamento, propriedade confusa, builds lentos).
|
|
16
|
+
- A estrutura do framework é respeitada onde ela sustenta algo (módulos NestJS, roteamento `app/` do Next.js), e os contextos são organizados dentro dela.
|
|
17
|
+
- Programas pequenos ficam planos: alguns arquivos em `src/` estão bem até começar a doer.
|
|
18
|
+
- Projetos JavaScript seguem as mesmas regras; os tipos vêm de JSDoc com `checkJs` quando o projeto o usa.
|
|
19
|
+
|
|
20
|
+
## Avalie primeiro
|
|
21
|
+
|
|
22
|
+
Somente leitura:
|
|
23
|
+
|
|
24
|
+
1. `tsc --noEmit` (ou `tsc -b` com project references): o build é a linha de base.
|
|
25
|
+
2. Ciclos: `npx madge --circular --extensions ts,tsx src` (ou `npx dpdm`). Em TS, ciclos compilam e falham em tempo de execução como imports `undefined` ou erros de zona morta temporal.
|
|
26
|
+
3. Quem importa quem: `npx depcruise src --output-type text` ou `madge --image`. Procure arquivos de domínio importando infraestrutura (ORM, clientes HTTP, SDKs, `process.env`).
|
|
27
|
+
4. Barrel files: arquivos `index.ts` que só reexportam. Eles escondem o grafo real de dependências e criam ciclos.
|
|
28
|
+
5. Nomes de pastas: os genéricos (`utils`, `common`, `helpers`, `shared`, `lib`, `types`, `models`, `services`) são um mau sinal.
|
|
29
|
+
6. Código morto e dependências sem uso: `npx knip`.
|
|
30
|
+
7. Formato de módulo: `"type"` no `package.json`, `module`/`moduleResolution` no `tsconfig.json`. ESM e CommonJS misturados são um achado por si só.
|
|
31
|
+
|
|
32
|
+
## Estrutura alvo
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
src/
|
|
36
|
+
main.ts # raiz de composição: config, montagem, start. Sem lógica de negócio.
|
|
37
|
+
<contexto>/ # um por contexto delimitado, ex.: booking/, billing/
|
|
38
|
+
domain/ # entidades, objetos de valor, políticas, interfaces de repositório. TS puro.
|
|
39
|
+
application/ # casos de uso; depende só do domínio
|
|
40
|
+
adapters/
|
|
41
|
+
http/ # controllers/rotas deste contexto
|
|
42
|
+
persistence/ # implementa as interfaces de repositório do domínio
|
|
43
|
+
platform/ # infraestrutura transversal com comportamento real: db, logging, config
|
|
44
|
+
test/ # testes de integração e e2e (os unitários ficam junto do código)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Com NestJS, cada contexto é um módulo Nest (`booking.module.ts`) que monta os próprios providers; `domain/` fica livre de decorators do Nest. Num front-end, a mesma ideia vale como pastas por funcionalidade (`features/<contexto>/`), com os componentes básicos de UI num pacote de design system, e não num `components/` guardando tudo.
|
|
48
|
+
|
|
49
|
+
Regras:
|
|
50
|
+
|
|
51
|
+
- **Organize por contexto, não por camada.** Divida um contexto em `domain/application/adapters` só quando ele crescer; um contexto pequeno pode ter três arquivos.
|
|
52
|
+
- **As dependências apontam para dentro.** `domain/` importa só a biblioteca padrão e o próprio contexto. `adapters/` importam o domínio, nunca o contrário. `process.env` é lido em `platform/config` e passado adiante.
|
|
53
|
+
- **As interfaces pertencem a quem as consome.** O domínio declara `interface BookingRepository`; o adaptador de persistência a implementa. A tipagem estrutural torna isso gratuito; não crie uma interface ao lado da sua única implementação "para testar".
|
|
54
|
+
- **Os contextos conversam por costuras explícitas:** o serviço de aplicação do outro contexto ou eventos publicados, nunca seus arquivos internos. Respeite as relações do mapa de contextos (uma Camada Anticorrupção é um módulo que traduz).
|
|
55
|
+
- **Sem barrel files** dentro da aplicação. Importe o arquivo que define a coisa. A API pública de um pacote é o campo `exports` do `package.json`, não um `index.ts` que reexporta o mundo.
|
|
56
|
+
- **Sem pastas genéricas.** Um utilitário vai para o módulo que o usa, ou para um módulo com o nome do que ele faz (`money.ts`, `clock.ts`).
|
|
57
|
+
- **Aliases de caminho são ergonomia, não fronteira.** `@booking/*` em `paths` do `tsconfig` não impede um import proibido; uma regra de dependência impede.
|
|
58
|
+
- **Verifique as regras no CI:** regras do `dependency-cruiser`, `eslint-plugin-boundaries` ou `no-restricted-imports` por pasta. Uma regra que não é verificada é uma sugestão.
|
|
59
|
+
- **Um pacote só**, a menos que partes sejam versionadas ou publicadas separadamente. Aí use workspaces (npm/pnpm) e project references do TypeScript, com cada pacote expondo sua API pelo `exports`.
|
|
60
|
+
- **Um formato de módulo só.** Código novo é ESM (`"type": "module"`, `module: "nodenext"`, imports relativos com extensão `.js`), a menos que o projeto seja CommonJS de propósito.
|
|
61
|
+
|
|
62
|
+
## Plano de movimentação
|
|
63
|
+
|
|
64
|
+
Cada passo compila e passa nos testes sozinho, para poder ser um commit próprio:
|
|
65
|
+
|
|
66
|
+
1. Quebre os ciclos primeiro (mova o tipo compartilhado para o módulo dono do conceito, ou inverta com uma interface do lado de quem consome).
|
|
67
|
+
2. Remova os barrel files nos caminhos que você vai mover, apontando os imports para o arquivo que define.
|
|
68
|
+
3. Crie a pasta do contexto e mova os arquivos de domínio.
|
|
69
|
+
4. Mova os adaptadores para trás das interfaces do domínio.
|
|
70
|
+
5. Atualize a raiz de composição (`main.ts` ou o módulo raiz do Nest).
|
|
71
|
+
6. Adicione as regras de dependência ao CI para a estrutura não regredir.
|
|
72
|
+
7. Apague as pastas genéricas que ficaram vazias.
|
|
73
|
+
|
|
74
|
+
Use a refatoração "mover arquivo" do editor (ela reescreve os imports), ou `ts-morph` para movimentações grandes. Rode `tsc --noEmit` e os testes depois de cada passo. Evite localizar-e-substituir manual nos caminhos de import.
|
|
75
|
+
|
|
76
|
+
## Formato
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
## Estado atual
|
|
80
|
+
| Problema | Onde | Efeito |
|
|
81
|
+
|
|
82
|
+
## Árvore alvo
|
|
83
|
+
<árvore>
|
|
84
|
+
|
|
85
|
+
## Regras de dependência
|
|
86
|
+
<imports permitidos entre pastas, e a ferramenta/config que os verifica>
|
|
87
|
+
|
|
88
|
+
## Plano de movimentação
|
|
89
|
+
| # | Passo | Arquivos afetados | Commit |
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Próximo
|
|
93
|
+
|
|
94
|
+
- `ts-code-review` verifica se o código novo respeita as regras de dependência.
|
|
95
|
+
- `commit-message`: um commit `refactor` por passo.
|
|
96
|
+
|
|
97
|
+
## Evite
|
|
98
|
+
|
|
99
|
+
- `models/`, `services/`, `controllers/`, `utils/` no primeiro nível.
|
|
100
|
+
- Barrel files `index.ts` reexportando uma pasta inteira.
|
|
101
|
+
- Aliases de caminho do `tsconfig` usados como se fossem fronteiras.
|
|
102
|
+
- Arquivos de domínio importando o ORM, o framework HTTP ou `process.env`.
|
|
103
|
+
- Dividir em muitos pacotes de workspace antes de qualquer coisa ser publicada separadamente.
|
|
104
|
+
- Reorganizações de uma vez num commit só.
|