forjajs 5.0.0 → 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 +68 -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/create-memory-nest-kit.js +0 -0
- package/dist/bin/forja.js +0 -0
- 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-upgrade.d.ts +0 -4
- package/dist/lib/project-upgrade.js +19 -1
- 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/dist/scripts/project-upgrade.js +9 -6
- package/docs/init-project.md +1 -1
- package/docs/llm-fit-loop.md +16 -0
- package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +1 -1
- 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 +2 -2
- 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,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: requirements-gathering
|
|
3
|
+
description: Use quando transformar ideias, achados de elicitação ou documentos numa especificação de requisitos estruturada: escopo, atores, requisitos funcionais com critérios de aceite, regras de negócio, requisitos não funcionais mensuráveis, glossário e prioridades.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Levantamento de Requisitos
|
|
7
|
+
|
|
8
|
+
Consolida o que se sabe sobre um sistema numa especificação de requisitos curta e verificável. Entrada: uma ideia, achados de elicitação (skill `requirements-elicitation`), documentos existentes ou um sistema legado. Saída: a especificação que `domain-modeling` consome.
|
|
9
|
+
|
|
10
|
+
A especificação é uma lista de trabalho, não literatura. Detalhe só o que é incerto e está perto de ser construído; o longo prazo fica como direção.
|
|
11
|
+
|
|
12
|
+
A especificação está pronta quando um desenvolvedor consegue implementá-la sem adivinhar e um testador consegue verificá-la sem interpretar.
|
|
13
|
+
|
|
14
|
+
## Convenções
|
|
15
|
+
|
|
16
|
+
- Termos em pt-BR seguidos do en-US: Requisito Funcional (Functional Requirement), Regra de Negócio (Business Rule), Requisito Não Funcional (Non-Functional Requirement), Critério de Aceite (Acceptance Criterion), Ator (Actor), Parte Interessada (Stakeholder), Escopo (Scope), Linguagem Ubíqua (Ubiquitous Language).
|
|
17
|
+
- IDs: `RF-NN` (funcional), `RN-NN` (regra de negócio), `RNF-NN` (não funcional). Nunca reutilize um ID; marque itens removidos como removidos.
|
|
18
|
+
- Escreva no vocabulário das partes interessadas.
|
|
19
|
+
|
|
20
|
+
## Princípio central
|
|
21
|
+
|
|
22
|
+
Um requisito descreve **o quê** e **por quê**, nunca **como**. "A enfermeira precisa ver a dieta do paciente antes de fazer o pedido" é um requisito; "mostrar um selo de dieta na tela de pedido" é uma solução. Se a entrada trouxer uma solução, registre o problema por trás dela e mantenha a solução como nota.
|
|
23
|
+
|
|
24
|
+
Especifique exatamente o necessário: nem acima (soluções, decisões de design) nem abaixo (lacunas que quem implementa terá de preencher adivinhando).
|
|
25
|
+
|
|
26
|
+
## Qualidade de cada item
|
|
27
|
+
|
|
28
|
+
Todo requisito e regra precisa ser:
|
|
29
|
+
- **Atômico**: uma necessidade por item.
|
|
30
|
+
- **Verificável**: checável por um teste, uma métrica ou um comportamento observável; tem critérios de aceite ou um exemplo. Se não dá para checar, é um desejo, não um requisito: reescreva ou descarte.
|
|
31
|
+
- **Com fonte**: quem disse ou de onde veio.
|
|
32
|
+
- **Sem ambiguidade**: ambiguidade é defeito. Se dá para ler de duas formas, reescreva até sobrar uma leitura só. Nada de "rápido", "fácil", "flexível", "amigável", "etc.", "e/ou" sem definição.
|
|
33
|
+
- **Completo**: cobre os casos de borda, não só o caminho feliz.
|
|
34
|
+
|
|
35
|
+
Itens que falham nessas verificações vão para **Perguntas em aberto**, não para a lista.
|
|
36
|
+
|
|
37
|
+
## Processo
|
|
38
|
+
|
|
39
|
+
### 1. Objetivo e contexto
|
|
40
|
+
Um parágrafo: que problema é resolvido, para quem, e como o sucesso é reconhecido. Sem isso, nada pode ser priorizado.
|
|
41
|
+
|
|
42
|
+
### 2. Atores e partes interessadas
|
|
43
|
+
Quem interage com o sistema (atores) e quem é afetado por ele (partes interessadas). Inclua sistemas externos como atores.
|
|
44
|
+
|
|
45
|
+
### 3. Escopo
|
|
46
|
+
Escopo é um contrato. Listas explícitas de **dentro** e **fora**. O "fora" impede o crescimento silencioso do escopo e é tão importante quanto o "dentro".
|
|
47
|
+
|
|
48
|
+
### 4. Requisitos funcionais
|
|
49
|
+
Frases curtas: `<Ator> precisa conseguir <ação> para <objetivo>`. Para cada um, 1–4 critérios de aceite em Dado/Quando/Então ou exemplos concretos. Os critérios cobrem modos de falha, entradas inválidas ou inesperadas e limites, não só o caminho feliz; um requisito só com critérios de caminho feliz está incompleto.
|
|
50
|
+
|
|
51
|
+
### 5. Regras de negócio
|
|
52
|
+
Separadas dos requisitos funcionais: as regras que governam o domínio independentemente das telas (limites, elegibilidade, cálculos, prazos, estados, quem pode fazer o quê). Enuncie cada regra com um exemplo. Regras que variam ou podem mudar são marcadas como **variáveis**: virarão Políticas em `domain-modeling`.
|
|
53
|
+
|
|
54
|
+
### 6. Requisitos não funcionais
|
|
55
|
+
Só os mensuráveis, e só os que importam aqui: desempenho (latência num volume declarado), disponibilidade, segurança, auditabilidade, retenção de dados, compliance (dados pessoais → sinalize para `lgpd-compliance`), integrações, acessibilidade. Um requisito não funcional sem número ou condição verificável vai para perguntas em aberto.
|
|
56
|
+
|
|
57
|
+
### 7. Glossário
|
|
58
|
+
Termos do domínio com seu significado e o contexto em que se aplicam. É a semente da linguagem ubíqua. Quando um termo tem dois significados, registre os dois: isso sinaliza dois contextos delimitados.
|
|
59
|
+
|
|
60
|
+
### 8. Prioridade
|
|
61
|
+
MoSCoW por requisito funcional: **Must** (sem ele o sistema não tem razão de existir), **Should**, **Could**, **Won't (agora)**. Poucos Musts. Se tudo é Must, pergunte o que seria cortado se o prazo caísse pela metade.
|
|
62
|
+
|
|
63
|
+
### 9. Suposições e perguntas em aberto
|
|
64
|
+
O que foi suposto sem confirmação e o que ainda precisa ser perguntado, e a quem. Incógnitas são listadas, nunca preenchidas com palpites. Quando faltar informação-chave, uma lista precisa e direcionada de perguntas é o entregável; prefira-a a uma especificação construída sobre suposições.
|
|
65
|
+
|
|
66
|
+
### 10. Encaminhamento
|
|
67
|
+
Anote o que vai para onde: regras de negócio e glossário → `domain-modeling`; critérios de aceite → `testing` (mais a skill da linguagem, por exemplo `ts-testing`); dados pessoais → `lgpd-compliance`; incertezas técnicas → `technical-spike`.
|
|
68
|
+
|
|
69
|
+
## Formato de saída
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
# Requisitos: <sistema ou funcionalidade>
|
|
73
|
+
|
|
74
|
+
## Objetivo
|
|
75
|
+
<problema, para quem, critério de sucesso>
|
|
76
|
+
|
|
77
|
+
## Atores
|
|
78
|
+
| Ator | Descrição |
|
|
79
|
+
|
|
80
|
+
## Escopo
|
|
81
|
+
- Dentro: ...
|
|
82
|
+
- Fora: ...
|
|
83
|
+
|
|
84
|
+
## Requisitos funcionais
|
|
85
|
+
### RF-01 — <título curto> [Must]
|
|
86
|
+
<Ator> precisa conseguir <ação> para <objetivo>.
|
|
87
|
+
Fonte: <...>
|
|
88
|
+
Critérios de aceite:
|
|
89
|
+
- Dado ... Quando ... Então ...
|
|
90
|
+
|
|
91
|
+
## Regras de negócio
|
|
92
|
+
| ID | Regra | Exemplo | Variável? | Fonte |
|
|
93
|
+
|
|
94
|
+
## Requisitos não funcionais
|
|
95
|
+
| ID | Requisito | Medida / condição | Fonte |
|
|
96
|
+
|
|
97
|
+
## Glossário
|
|
98
|
+
| Termo | Significado | Contexto |
|
|
99
|
+
|
|
100
|
+
## Suposições e perguntas em aberto
|
|
101
|
+
- <item> — perguntar a <quem>
|
|
102
|
+
|
|
103
|
+
## Encaminhamento
|
|
104
|
+
- domain-modeling: RN-..., glossário
|
|
105
|
+
- testing: critérios de aceite de RF-...
|
|
106
|
+
- lgpd-compliance: <dados pessoais envolvidos>
|
|
107
|
+
- technical-spike: <incertezas>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## No Forja
|
|
111
|
+
|
|
112
|
+
No Forja, a especificação vive em `specs/<slug>/spec.md`, criada com `forja spec:new <slug>`. Mapeie as seções:
|
|
113
|
+
|
|
114
|
+
| Esta skill | spec.md do Forja |
|
|
115
|
+
|---|---|
|
|
116
|
+
| Objetivo | §1 Problema e §2 Proposta de valor |
|
|
117
|
+
| Requisitos funcionais (`RF-NN`) | §3 User stories |
|
|
118
|
+
| Critérios de aceite | §4 Critérios de aceite, como `AC-n` (cite o `RF-NN` de origem) |
|
|
119
|
+
| Escopo | §5 Escopo (Dentro / Fora) |
|
|
120
|
+
| Requisitos não funcionais | §6 NFRs / restrições |
|
|
121
|
+
| Riscos e suposições | §7 Riscos e mitigação |
|
|
122
|
+
|
|
123
|
+
Regras de negócio e glossário também vão para `memory/30-domains/<contexto>/`. Ao terminar a revisão: `forja spec:set-status <slug> spec approved`; depois `forja spec:check <slug>`.
|
|
124
|
+
|
|
125
|
+
## Evite
|
|
126
|
+
|
|
127
|
+
- Soluções escritas como requisitos (telas, tabelas, tecnologias).
|
|
128
|
+
- Documentos de casos de uso com dezenas de páginas.
|
|
129
|
+
- Detalhar o futuro distante.
|
|
130
|
+
- Requisitos não funcionais vagos ("o sistema precisa ser rápido").
|
|
131
|
+
- Manter desejos (afirmações não testáveis) como requisitos.
|
|
132
|
+
- Critérios de aceite só de caminho feliz.
|
|
133
|
+
- Regras de negócio escondidas dentro de requisitos funcionais.
|
|
134
|
+
- Preencher lacunas com regras inventadas.
|
|
@@ -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.
|