---
type: rule
name: typescript-sem-any
trigger: always_on
description: Proíbe uso de any, casts inseguros e padroniza uso de enums em código TypeScript
scope: global
updatedAt: "2026-06-01"
globs:
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.vue"
alwaysApply: true
---

Regras obrigatórias para TypeScript neste projeto:

- Nunca usar `any`.
- Nunca usar `as any`.
- Nunca contornar erro de tipagem com cast forçado.
- Quando o tipo não for conhecido, usar `unknown`.
- Antes de acessar valores `unknown`, fazer narrowing com:
  - `typeof`
  - `in`
  - `Array.isArray`
  - type guards
  - schemas de validação como Zod
- Preferir:
  - generics
  - union types
  - `Record<string, unknown>`
  - `Partial<T>`
  - `Pick<T, K>`
  - `PropType<T>` em Vue
  - tipos derivados de funções existentes
- Se faltar tipo, o agente deve:
  1. procurar tipos já existentes no projeto;
  2. criar um tipo/interface local explícita;
  3. inferir a partir do contexto sempre que possível;
  4. deixar um `TODO de tipagem` explícito, mas sem usar `any`.

Regras obrigatórias para uso de enums:

- Quando um valor estiver associado a um `enum`, é obrigatório utilizar o enum, nunca strings literais.
- O acesso deve seguir o padrão: `<NomeEnum>.VALOR`.

Também é proibido, quando existir `enum` correspondente:

- utilizar strings literais no lugar do enum (ex: `"ativo"`, `"inativo"`, `"automatica"`, `"criar"`);
- utilizar cast para forçar compatibilidade com enum (ex: `"ativo" as StatusConta`).

Proibido gerar código que apenas "faça compilar" usando:

- `as any`
- `: any`
- `[] as any`
- `{ } as any`
- dupla coerção como `as unknown as any`

Em casos excepcionais, preferir:

- `as unknown as TipoEspecifico` somente se houver justificativa clara e comentário técnico.

Diretriz para o agente:

Se encontrar uma string que represente um valor de domínio do sistema, o agente deve:

1. procurar se já existe um `enum` correspondente no projeto;
2. usar o `enum` existente;
3. se não existir, propor a criação de um `enum` explícito, em vez de manter strings soltas.

---

## Referências

- Skill: `global/skills/diagnosticar-erros-build/SKILL` (quando erros de tipagem causam falhas de build em cascata)
- Workflow: `global/workflows/otimizar-codigos` (padrão de documentação para casts temporários)