---
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 Inegociáveis para Uso de Enums e zEnums

> 🚨 **REGRA DE OURO:** **SE EXISTE ENUM OU zENUM DISPONÍVEL (EM QUALQUER MÓDULO OU APLICAÇÃO), O USO DO ENUM É 100% OBRIGATÓRIO — SEM NENHUMA EXCEÇÃO.**

1. **Proibição Universal de Strings Literais (Magic Strings):**
   - É **estritamente proibido** utilizar strings literais no lugar de qualquer enum ou zEnum existente no sistema (seja para tabelas, colunas, status, tipos, categorias, eventos, ações, etc.).
   - É proibido utilizar casts para forçar compatibilidade com tipos de domínio (ex: `"ativo" as StatusConta` ou `"pontos" as TipoNomeTabela`).

2. **Padrão Canônico de Acesso:**
   - Enums TypeScript nativos: `<NomeEnum>.VALOR` (ex: `CategoriasSuporte.ADMIN`, `TipoProcessamento.BATCH`).
   - Enums Zod / Objetos derivados: `<zSchema>.enum.VALOR` ou `<enumDerivado>.<membro>` (ex: `enumTabelas.pontos`, `enumColunas.codigo`, `zStatus.enum.ativo`, `zTipoPessoa.enum.fisica`).

3. **Operações em Todas as Camadas (Banco, Filas, APIs e Frontend):**
   - **Banco de dados & Queries:** Nomes de tabelas, entidades e colunas DEVEM consumir os enums correspondentes do pacote `*-comuns` (nunca strings hardcoded em queries de banco).
   - **Regras de Negócio & Lógica:** Comparações condicionais, transições de estado, status e categorias DEVEM usar os membros do enum.
   - **Frontend & Telas:** Filtros, selects, badges e renderizações condicionais DEVEM importar e referenciar os enums canônicos.

4. **Diretriz de Busca Prévia Obrigatória:**
   Antes de escrever qualquer string que represente conceito de domínio, entidade, tabela, coluna, status ou opção, o agente **DEVE**:
   1. Inspecionar o pacote `*-comuns` (`src/enums/`, `src/tabelas/`, `src/tipos/`) da respectiva aplicação;
   2. Se existir qualquer enum correspondente, **é obrigatório utilizar o enum existente**;
   3. Se não existir, propor/criar o `enum` ou `z.enum` no `*-comuns` em vez de espalhar strings literais.

---

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