Receita: Auditoria de Stack

Uma auditoria de stack responde a três perguntas: O nosso grafo de dependências está saudável? Estamos acumulando dívida técnica? O que devemos fazer upgrade em seguida e em qual ordem?

Esta receita usa as ferramentas do Stream H do SpecForge para executar uma auditoria completa de saúde da stack e construir um plano de upgrade acionável.

---

Etapa 1 — Executar a Auditoria Completa da Stack

Prompt:

Audite a stack do projeto proj_abc123

O que esperar:

Stack Health Score: 71/100

Status das Dependências:
  up_to_date:    34 pacotes  ✅
  outdated:      12 pacotes  ⚠️
  vulnerable:     3 pacotes  🚨
  unmaintained:   1 pacote   ❌

Crítico (corrigir imediatamente):
  - lodash 4.17.20 → CVE-2021-23337 (Prototype pollution)
  - axios 0.21.1 → CVE-2023-45857 (Vulnerabilidade CSRF)
  - follow-redirects 1.14.7 → CVE-2023-26159

Alta Prioridade (próximo sprint):
  - typescript 4.9.5 → 5.7.2 (13 versões minor atrasado)
  - vitest 0.34.0 → 3.1.0 (versão major atrasada)
  - express 4.18.0 → 5.0.1 (versão major disponível)

Prioridade Média (este trimestre):
  - 8 pacotes 1–3 versões minor atrás

---

Etapa 2 — Detectar APIs Depreciadas

Prompt:

Detecte APIs depreciadas no projeto proj_abc123

Isso varre arquivos fonte (sem necessidade de rede) em busca de uso de APIs depreciadas:

Uso de API Depreciada Encontrado:

src/middleware/session.ts:14
  express-session secret como string — depreciado, use array de secrets
  Esforço para corrigir: 0,5h

src/utils/crypto.ts:8
  crypto.createCipher — depreciado desde Node 10, use createCipheriv
  Risco de segurança: ALTO
  Esforço para corrigir: 2h

src/config/database.ts:22
  callback de mongoose.connect — depreciado no Mongoose 7, use promise
  Esforço para corrigir: 1h

Dívida técnica total: ~3,5h

---

Etapa 3 — Planejar Upgrades Prioritários

Para cada item crítico ou de alta prioridade, gere um plano de upgrade:

Prompt:

Planeje o upgrade do axios 0.21.1 para a versão estável mais recente do projeto proj_abc123

O que esperar:

## Plano de Upgrade do Axios: 0.21.1 → 1.7.9

### Breaking Changes
- AbortController substitui CancelToken (depreciado na v0.22)
- Content-Type padrão para POST alterado para application/json (sem mudança necessária)
- Tipos de resposta alterados nas definições TypeScript

### Etapas de Migração
1. Atualizar package.json: axios ^1.7.9
2. Substituir todo uso de CancelToken:
   - Buscar: axios.CancelToken.source()
   - Substituir: AbortController / AbortSignal
3. Atualizar tipos TypeScript (generic de AxiosResponse alterado)
4. Executar suite de testes — interceptors do axios são compatíveis retroativamente

### Arquivos afetados (5):
- src/api/client.ts (uso de CancelToken nas linhas 34, 67)
- src/api/interceptors.ts (cancelamento de token na linha 89)
- src/utils/request.ts (tratamento de timeout)
- tests/api/client.test.ts (atualizações de mock necessárias)
- tests/api/interceptors.test.ts (atualizações de mock necessárias)

### Esforço estimado: 3h
### Rollback: fixar na 0.27.2 (último 0.x estável)

---

Etapa 4 — Criar Specs para Upgrades Principais

Para upgrades de versão major que afetam múltiplos arquivos, crie uma spec adequada:

Prompt:

Crie uma spec para fazer upgrade do Express de 4.18 para 5.0 no projeto proj_abc123

Isso fornece:

• Critérios de aceitação para o upgrade (todos os endpoints ainda funcionam, sem mudança de comportamento)
• Um plano de migração
• Requisitos de cobertura de testes (comparação antes + depois)

---

Etapa 5 — Verificação de Governança de Dados

Se o projeto lida com dados de usuários:

Prompt:

Execute uma verificação de governança de dados para o projeto proj_abc123

O que esperar:

Detecção de PII:
  spec SPEC-003 (registro de usuário): e-mail, nome, telefone — precisa de política de retenção
  spec SPEC-007 (analytics): endereço IP armazenado — interesse legítimo GDPR necessário

Conformidade com GDPR:
  ✅ Minimização de dados — specs coletam PII mínimo
  ⚠️  Política de retenção faltando para user.email (SPEC-003)
  ⚠️  Direito de exclusão não especificado em nenhuma spec
  ❌  Nenhuma spec de aviso de privacidade existe

Recomendações:
  1. Criar spec para conformidade LGPD/GDPR (direito de exclusão, exportação de dados)
  2. Adicionar política de retenção à SPEC-003
  3. Gerar template de aviso de privacidade

---

Etapa 6 — Priorizar o Backlog de Remediação

Prompt:

Crie specs para as 3 principais vulnerabilidades de segurança encontradas na auditoria de stack do projeto proj_abc123

O SpecForge cria specs para cada correção de CVE, adequadamente delimitadas com critérios de aceitação.

---

Etapa 7 — Acompanhar o Progresso

Agende auditorias regulares e acompanhe o StackHealthScore ao longo do tempo:

Prompt:

Audite a stack do projeto proj_abc123

Meta: StackHealthScore ≥ 85, zero pacotes vulnerable ou unmaintained.

---

Recomendações de Cadência de Auditoria

Gatilho	Ação
Mensal	audit_stack — varredura completa de dependências
Trimestral	detect_deprecations — varredura do código fonte
Pré-release	audit_stack + security_check nas specs de pagamento/autenticação
Pós-incidente	capture_learning + atualizar specs afetadas
LTS principal do Node.js	detect_deprecations + plan_upgrade para pacotes afetados

---

Achados Comuns e Correções

Achado	Ferramenta	Tempo típico de correção
CVE em dependência direta	plan_upgrade	1–4h
CVE em dependência transitiva	plan_upgrade + override manual	2–8h
API depreciada no código fonte	detect_deprecations	0,5–3h por arquivo
Pacote não mantido	Substituir por fork mantido	4–16h
Versão major atrasada	plan_upgrade	2–12h