---
name: diagnosticar-erros-build
scope: global
updatedAt: "2026-06-01"
description: >
  Guia operacional para diagnosticar e resolver erros de build em cascata em monorepos TypeScript.
---

# Skill: Diagnosticar Erros de Build em Monorepo TypeScript

Use esta skill quando o build de um monorepo TypeScript falha — especialmente quando erros aparecem em pacotes que não foram diretamente modificados (erros em cascata).

---

## PASSO 1 — Capturar o Erro Completo

Executar o build com output completo e sem truncamento:

```bash
# pnpm (monorepo completo)
pnpm build 2>&1 | head -200

# Pacote específico
pnpm --filter <pacote> build 2>&1

# tsc direto (se disponível)
npx tsc --noEmit --pretty 2>&1 | head -100
```

Identificar:

- **Qual pacote falhou primeiro** (nem sempre é o que aparece no topo)
- **Código do erro** (`TS2304`, `TS2345`, `TS7006`, etc.)
- **Arquivo e linha** do erro original

---

## PASSO 2 — Classificar o Tipo de Erro

### Erros de dependência entre pacotes (cascata)

| Sintoma | Causa provável | Solução |
|---------|---------------|---------|
| `Cannot find module '@org/xxx'` | Pacote não foi buildado antes | Buildar na ordem correta ou usar `references` |
| `Module has no exported member 'X'` | Tipo renomeado/removido no pacote origem | Atualizar import no consumidor |
| Tipos `any` infiltrados | Pacote exporta sem `.d.ts` | Verificar `declaration: true` no tsconfig |
| `The inferred type cannot be named` | Dependência circular de tipos | Extrair tipo para pacote compartilhado |

### Erros de configuração

| Sintoma | Causa provável | Solução |
|---------|---------------|---------|
| `Cannot use import statement` | `module` errado no tsconfig | Alinhar `module`/`moduleResolution` |
| `Relative import paths need extensions` | Node16/NodeNext resolution | Adicionar `.js` nos imports ou mudar para `bundler` |
| `rootDir is expected to contain all source files` | Arquivo fora do `rootDir` | Ajustar `rootDir` ou mover arquivo |
| `Referenced project must have setting composite` | Project references sem `composite` | Adicionar `composite: true` no tsconfig referenciado |

### Erros de tipagem

| Sintoma | Causa provável | Solução |
|---------|---------------|---------|
| `TS2304: Cannot find name` | Tipo global não declarado | Criar `d.ts` ou importar explicitamente |
| `TS2345: Argument not assignable` | Tipos incompatíveis entre versões | Alinhar versão da dependência |
| `TS7006: Parameter implicitly has 'any'` | `noImplicitAny` ativado | Tipar o parâmetro explicitamente |
| `TS18046: is of type 'unknown'` | Narrowing ausente | Fazer type guard antes de usar |

---

## PASSO 3 — Identificar a Raiz do Problema

O erro que aparece **primeiro** nem sempre é a raiz. Seguir esta estratégia:

### 3.1. Verificar ordem de build

```bash
# Listar dependências internas para entender ordem correta
rg '"workspace:' --include='package.json' -l | sort

# Se usar turbo, verificar o pipeline
cat turbo.json | jq '.pipeline.build'
```

### 3.2. Rebuild isolado do pacote raiz

```bash
# Buildar APENAS o pacote mais baixo na hierarquia que apresenta erro
pnpm --filter <pacote-raiz> build

# Se esse buildar com sucesso, subir na hierarquia
pnpm --filter <pacote-consumidor> build
```

### 3.3. Verificar checagem de tipos isolada

```bash
# Verificar se a tipagem está correta sem produzir output
npx tsc --noEmit -p <caminho>/tsconfig.json
```

---

## PASSO 4 — Resolver Erros em Cascata

### Estratégia: de baixo para cima

1. Identificar o pacote **mais fundamental** (aquele que não depende de outros internos)
2. Resolver TODOS os erros nesse pacote
3. Rebuildar
4. Subir para o próximo pacote na cadeia de dependência
5. Repetir até o topo

### Armadilhas comuns

```typescript
// ❌ ERRADO: "resolver" com any (viola typescript-sem-any)
const dados = resultado as any

// ✅ CORRETO: tipar adequadamente
const dados: ResultadoEsperado = resultado

// ❌ ERRADO: ignorar erro com @ts-ignore
// @ts-ignore
import { funcao } from '@org/pacote'

// ✅ CORRETO: investigar por que o import falha
// O pacote '@org/pacote' foi buildado? O export existe?
```

---

## PASSO 5 — Verificar Alinhamento de Configuração

Quando erros persistem entre pacotes, verificar alinhamento de tsconfig:

```bash
# Comparar configurações críticas entre pacotes
for f in $(fd tsconfig.json --max-depth 2 --type f); do
  echo "=== $f ==="
  jq '{target, module, moduleResolution, strict, composite, declaration}' "$f" 2>/dev/null
done
```

Campos que **devem** ser consistentes entre pacotes do mesmo monorepo:

| Campo | Recomendação |
|-------|-------------|
| `target` | Mesmo alvo para todos (ex: `ES2022`) |
| `module` | Consistente (ex: `ESNext` ou `Node16`) |
| `moduleResolution` | Consistente (ex: `bundler` ou `node16`) |
| `strict` | `true` em todos |
| `declaration` | `true` em libs, opcional em apps |
| `composite` | `true` em libs referenciadas |

---

## PASSO 6 — Limpar e Rebuildar

Quando a investigação não revela causa óbvia:

```bash
# Limpar artefatos de build de todos os pacotes
fd -t d 'dist|build|.tsbuildinfo' --exclude node_modules | xargs rm -rf

# Limpar node_modules (último recurso)
fd -t d node_modules --max-depth 2 | xargs rm -rf

# Reinstalar e rebuildar do zero
pnpm install && pnpm build
```

---

## Checklist Final

- [ ] O pacote raiz do erro em cascata foi identificado?
- [ ] O erro original (não o efeito cascata) foi localizado?
- [ ] A solução não usa `any`, `as any` ou `@ts-ignore`?
- [ ] Todos os pacotes na cadeia foram rebuildados após a correção?
- [ ] As configurações de tsconfig estão alinhadas entre pacotes?
- [ ] O build completo passa sem erros?

## Referências

- Rules: `.agent/rules/typescript-sem-any.global.md`
- Workflow: `.agent/workflows/otimizar-codigos.global.md`
- Skill: `.agent/skills/mapear-codigo-fonte.global/SKILL.md`