docs: auditorias de cobertura de logs do serviço

[nicholas-maestrello]

O que é

Adiciona docs/log-coverage-audits/, com duas auditorias independentes dos caminhos de erro de node/ feitas sobre o commit 508bff6, mais um README com o histórico e as convenções.

São só documentos — nenhuma mudança de código neste PR. A intenção é dupla:

1. Dar rastreabilidade aos caminhos de falha silenciosa que ainda estão abertos, cada um com arquivo, linha e um trecho de correção sugerido no estilo de logging que o repo já usa.
2. Registrar as decisões deliberadas de logging na seção "Verificado e considerado adequado", para que não sejam reabertas a cada revisão. O caso mais claro é o .catch(() => null) de directives/withSession.ts:26, que foi trocado por SessionMetric justamente por volume de log.

Achados

A camada de autenticação (directives/helper.ts e os quatro directives de acesso) está bem instrumentada: todo caminho de negação loga warn com o conjunto completo de metricFields. O mesmo vale para praticamente todo resolver de mutation.

O achado mais relevante é que setProfile não registra o erro quando uma das chamadas a clientes externos falha. No commit auditado, seis chamadas dentro dele não tinham .catch() e a função não tinha try/catch externo — uma indisponibilidade do b2b-organizations-graphql derrubava todo setProfile sem uma linha de log do serviço.

Atenção: o achado principal mudou de forma no master

O commit auditado está 35 commits atrás do master, que reescreveu Routes/index.ts. Reconferi antes de abrir o PR e registrei na seção "Nota sobre o master":

• O setProfile do master agora envolve cada chamada em timedSetProfile (Routes/index.ts:49). O catch desse wrapper (:75) loga em logger.debug com failed: true, sem o objeto error, e relança. O passo que falhou ficou identificável; o erro em si, não — e debug normalmente é filtrado em produção.
• setProfile continua sem try/catch no nível superior, e Routes.appSettings / services/appSettingsCache.ts:22 continuam sem guarda.

Ou seja, o achado continua aberto no master, só com outra forma. A correção mais direta hoje é o catch do timedSetProfile logar logger.error({ error, message: 'setProfile.stepFailed', step }) antes do throw, mais o try/catch externo.

Os números de linha dos dois relatórios valem para 508bff6 e estão declarados como tal no cabeçalho de cada um.

Sobre a diferença de score (89% vs. 77%)

Não é regressão de cobertura, e não é só granularidade. O lado coberto das duas auditorias praticamente coincide (85 e 86) — as duas acharam o mesmo conjunto de caminhos instrumentados.

A primeira auditoria mistura duas unidades no denominador: fechou 85 + 10 = 95, contando os cobertos um por um mas os achados como linhas de tabela agrupadas. Várias daquelas linhas cobrem vários locais (o LicenseManager é uma linha com 6 catches, o getUser é uma linha com o .catch mais 3 callers), e expandidas somam 21 locais, não 10. Normalizada para a mesma unidade, ela daria ~80%, não 89%.

A seção "Reconciliação dos scores" do relatório de revisão mostra a aritmética fechando: 21 locais, menos 1 inválido, mais os 6 dos achados novos, dá os 26 daqui. Deixei isso explícito para que a próxima auditoria não leia a queda como piora.

Notas de revisão

• Os dois relatórios são do mesmo commit; o segundo é uma contraprova independente do primeiro. Eles coincidem em 8 dos 10 achados originais e divergem em 3 pontos, todos listados na seção "Divergências da auditoria anterior".
• A divergência que mais importa: o primeiro relatório aponta Queries/Users.ts:592 como o achado mais grave, mas aquele branch é inalcançável (getUserByEmail sempre retorna um array de um elemento) e o caso de usuário não encontrado já é logado em getActiveUserByEmail:168. Sobra apenas :607.
• Mantive o primeiro relatório intacto em vez de corrigi-lo, para preservar o histórico.

Test plan

Não se aplica — mudança exclusivamente de documentação, sem alteração em node/.

[vtex-io-ci-cd]

Hi! I'm VTEX IO CI/CD Bot and I'll be helping you to publish your app! 🤖

Please select which version do you want to release:

• Patch (backwards-compatible bug fixes)

• Minor (backwards-compatible functionality)

• Major (incompatible API changes)

And then you just need to merge your PR when you are ready! There is no need to create a release commit/tag.

• No thanks, I would rather do it manually 😞

[vtex-io-docs-bot]

Beep boop 🤖

Thank you so much for keeping our documentation up-to-date ❤️