vue-componentes/.agent/skills/diagnosticar-erros-build.global/SKILL.md

name	scope	updatedAt	description
diagnosticar-erros-build	global	2026-06-01	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:

# 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

# 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

# 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

# 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

// ❌ 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:

# 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:

# 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