Erros de execução em português, com código específico, arquivo e linh…

[oxbar]

Erros de execução em português, com código específico, arquivo e linha

Fixes #100

Problema

Falhas de runtime chegavam ao console como LIQ99999: Cannot read properties of undefined (reading 'name') e ao cliente HTTP como o corpo literal [object Object] com Content-Type: text/plain. Sem português, sem código discriminante, sem arquivo/linha do código do usuário.

Diagnóstico

Eram três problemas independentes se somando:

1. Entrega — logicaComumErrosInterpretacao já montava um objeto JSON (REST) e até uma página HTML de erro rica (MVC), mas não definia tipoConteudo no retorno. Na expedição da resposta, sem tipoConteudo, o corpo caía no ramo text/plain e era coagido com String(corpo) — objetos viravam [object Object] e a página HTML do MVC (que já existia!) era exibida como texto cru.
2. Classificação — classificarErro mapeava por palavra-chave para um código, mas sem tradução: a mensagem crua do motor JavaScript (em inglês) era repassada, e quase tudo caía no genérico LIQ99999.
3. Localização — o caminho do arquivo fonte da rota existia no momento do registro (adicionarRota), mas nunca chegava à montagem das mensagens de erro; a linha do interpretador só aparecia em um dos dois ramos.

Solução

1. Entrega correta por arquétipo (fontes/liquido.ts):

• mvc → tipoConteudo: 'HTML' — a página de erro rica finalmente renderiza no navegador;
• rest → tipoConteudo: 'JSON' — resposta estruturada { mensagem, detalhes } com application/json;
• arquétipo desconhecido/ausente → fallback em JSON estruturado (antes: corpo undefined).

2. Taxonomia com mensagens em português (fontes/erros.ts): listaDeErros aceita mensagem amigável por entrada e ganha códigos para os erros de runtime mais comuns:

Código	Gatilho	Mensagem em português
LIQ20001	cannot read propert	Tentativa de acessar uma propriedade de um valor nulo ou indefinido.
LIQ20002	is not a function	Tentativa de chamar como função algo que não é uma função.
LIQ20003	is not defined	Uso de um nome que não foi definido.
LIQ20004	só pode chamar função ou classe	(já em português; ganha código próprio)
LIQ10000	erros de driver de banco	Mensagens amigáveis para rejeição/violação de restrição

A mensagem original é sempre preservada como detalhe técnico. LIQ99999 fica reservado ao que ainda não foi mapeado — e o caminho para eliminá-lo é adicionar entradas nesta lista.

3. Arquivo e linha do código do usuário: o arquivo fonte da rota é encanado do registro (adicionarRota, novo parâmetro opcional — sem quebra de compatibilidade; interface atualizada) até as mensagens, exibido relativo à raiz do projeto, junto da linha do interpretador quando disponível.

Antes e depois (mesmo cenário real)

Console:

ANTES:  [Liquido] LIQ99999: Cannot read properties of undefined (reading 'name')

DEPOIS: [Liquido] LIQ20001 [Arquivo: rotas/usuarios/[id].pitu, Linha: 2]:
        Tentativa de acessar uma propriedade de um valor nulo ou indefinido.
        (detalhe técnico: Cannot read properties of undefined (reading 'name'))

Cliente HTTP:

ANTES:  HTTP 500 | text/plain | [object Object]

DEPOIS (rest): HTTP 500 | application/json
{ "mensagem": "Ocorreu um erro interno na aplicação.",
  "detalhes": ["Código: LIQ20001 / Onde: Arquivo: rotas/clientes/[id].delegua, Linha: 2 / Mensagem: ... / Detalhe técnico: ... / Pilha: ..."] }

DEPOIS (mvc): HTTP 500 | text/html | página "Erro de Execução - Líquido" renderizada

Validação de ponta a ponta

Código compilado (tsc) e sobreposto ao pacote liquido@1.4.0 instalado, reproduzindo o erro real de parâmetro de rota (requisicao.parametros.id) em projetos Delégua (rest) e Pituguês (mvc) — os quatro resultados acima confirmados por requisição HTTP real.

Testes

• Novo testes/tratamento-erros.test.ts com 7 casos: JSON estruturado no REST (nunca [object Object]), tradução com código próprio e detalhe técnico preservado, arquivo + linha na saída, LIQ99999 apenas para não mapeados, tipoConteudo: 'HTML' no MVC, e fallback JSON para arquétipo desconhecido.
• testes/cadeia-middlewares.test.ts: uma expectativa atualizada para a nova assinatura de executarFuncaoRota (5º parâmetro opcional).
• Teste pré-existente da tela de erro MVC continua passando sem alteração.

Suíte unitária completa: 233 testes passando (23 suítes)
npx tsc --noEmit: sem erros

Fora do escopo (deliberadamente)

• Trecho de código-fonte na página de erro (estilo Next.js) — exigiria mapear hashArquivo → conteúdo via Importador; boa evolução futura sobre a base deste PR.
• Página 404 em inglês para rotas inexistentes (achado M1) — é o handler padrão do Express, camada diferente desta.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	83.81%	1149/1371
🟡	Branches	63.5%	454/715
🟢	Functions	88.27%	173/196
🟢	Lines	84.37%	1123/1331

Test suite run success

240 tests passing in 24 suites.

Report generated by 🧪jest coverage report action from 2302de3

[leonelsanchesdasilva]

Obrigado!