Vamos dar tipos mais precisos para a IA e para as pessoas: uma regra customizada do TypeScript ESLint para detectar tipos de retorno declarados de forma mais ampla do que a implementação

Ao analisar um codebase em TypeScript,
com frequência vemos casos em que a implementação de uma função retorna valores mais restritos, mas o tipo de retorno continua declarado de forma mais ampla.

Por exemplo, um código como este.

type Status = "idle" | "loading" | "error";  
  
function getStatus(isLoading: boolean): Status {  
  if (isLoading) return "loading";  
  return "idle";  
}  

A declaração de tipo inclui até error, mas a implementação real retorna apenas idle e loading.

Esse tipo de código é válido do ponto de vista do TypeScript, mas
pode levar a problemas como membros do tipo de retorno que ficaram sobrando depois de um refactor e não são mais usados,
ou a manutenção contínua de uma declaração de tipo de retorno mais ampla do que a implementação.

Na prática, senti que esses casos acontecem com frequência em situações como:
• membros de union que sobraram depois de um refactor
• declaração manual de tipo que não bate com a implementação
• annotations de tipo um pouco frouxas geradas por IA

Por isso,
criei uma regra customizada do TypeScript ESLint para detectar tipos de retorno declarados de forma mais ampla do que a implementação.

https://github.com/minseong0324/eslint-plugin-no-misleading-return-type

Por exemplo, ela cobre casos como:
• parte dos membros de um tipo union não é mais retornada
• o tipo é string, mas a implementação real retorna apenas um literal union mais restrito
• o tipo é Record<string, string>, mas a implementação real retorna um objeto as const com chaves específicas
• etc.

A intenção não é “vamos parar de escrever tipos de retorno”,
mas sim criar um guardrail que faça você revisar se o tipo de retorno declarado realmente corresponde à implementação.

Ainda existem casos complexos que a regra não suporta e pontos que precisam ser melhorados, mas
com a aceleração da geração de código na era da IA, senti que precisamos cada vez mais de mecanismos como esse para detectar automaticamente esse tipo de drift de tipos.

Feedback é bem-vindo.

[kwan03240324]

O que me deixa especialmente curioso é até onde devemos considerar isso um tipo de retorno intencionalmente mais amplo e a partir de que ponto ele passa a ser um tipo de retorno desalinhado com a implementação.