feat(reports): compare two metrics.json payloads field by field

[cpenaforte-clickbus]

Contexto e Motivação

O engine tem de provar que uma mudança interna não alterou o que ele emite. Duas frentes dependem disso e nenhuma tinha mecanismo: a otimização da busca de PR, cujo critério de aceite é metrics.json idêntico antes e depois no mesmo commit e na mesma janela; e a medição de paridade entre uma execução centralizada e uma local, que é critério de bloqueio do rollout.

Sem isso, "idêntico campo a campo" era afirmação que ninguém conseguia verificar sem abrir dois arquivos lado a lado e confiar no olho.

Closes #214

Mudanças

• iris/reports/metrics_diff.py — achata um payload em caminhos pontuados (grupo.subgrupo.chave, [i] para itens de lista) e reporta cada chave que difere, com os dois lados. A comparação é estrita em tipo: em Python True == 1 e 1 == 1.0, mas uma troca de tipo é mudança real no JSON emitido, e num payload de verdade 8 das 48 chaves float carregam valor integral (cascade_rate = 0.0, churn_couplings[0].coupling_rate = 1.0) — exatamente as que colidiriam com int. Container vazio achata para si mesmo, para que uma seção que sumiu não se confunda com chave que nunca existiu; a sentinela de ausência é objeto próprio porque None é valor legítimo no payload.
• scripts/compare_metrics.py — CLI no padrão do check_analysis_chain.py, com saídas 0 idênticos, 1 divergentes, 2 entrada inutilizável. Os quatro casos de entrada inutilizável (arquivo ausente, argumento ausente, caminho que é diretório, bytes não-UTF-8) saem 2; antes, diretório e não-UTF-8 escapavam como traceback e saíam 1, que no contrato do próprio script significa "divergente".
• tests/test_metrics_determinism.py — constrói um repositório real, roda o engine duas vezes e exige payloads iguais. Um segundo teste garante que a durabilidade rodou de fato, para o primeiro não passar por vacuidade. O repositório temporário fixa commit.gpgsign e core.hooksPath no próprio repo, para não depender da config global de git de quem roda: uma exigência global de assinatura, ou hooks herdados de um init.templateDir, quebrariam um teste cuja razão de existir é ser confiável na máquina de outra pessoa.
• A lista de ignorados nasce vazia, por medição: duas execuções no mesmo commit não divergiram em 103 nem em 190 chaves achatadas. Os dois candidatos derivados de tempo ficam documentados no código, com o motivo pelo qual seguem não provados, para entrarem só com prova de deriva num run real.

Plano de Teste

• pytest tests/test_metrics_diff.py -v — 23 testes cobrindo achatamento, divergência de valor e de tipo, ausência de chave em cada lado, ordenação, ignorados exatos e por curinga de um segmento, e as cinco saídas do CLI
• pytest tests/test_metrics_determinism.py -v — 2 testes: duas execuções do engine no mesmo commit batem, e a durabilidade rodou de fato
• pytest tests/ -q — a suíte inteira, sem regressão
• Manual: python scripts/compare_metrics.py a.json b.json com dois arquivos que diferem em uma chave imprime o caminho e sai 1

A verificação roda fora da máquina de quem construiu: o job cli do CI executa pytest tests/ -q a cada push.

Impacto e Risco

Risco baixo. Nada existente muda de comportamento: dois arquivos novos, um módulo novo, nenhuma assinatura pública alterada, nenhuma dependência nova — só stdlib. Nenhuma migração, nenhuma rota, nenhum contrato de dados. Nenhum arquivo sob .github/ foi tocado: o portão entra no pytest tests/ -q que o job cli já roda.

O único efeito no que já roda é o tempo de CI: o teste de determinismo executa o engine três vezes, contra repositórios temporários de 6 commits.

Sobre o tamanho (RFC 0028 §2.4): 494 linhas alteradas, faixa 251–500, que pede justificativa de por que não foi dividido. A justificativa é que o comparador e seu único consumidor não deveriam entrar separados — o módulo chegaria à main sem chamador, e o portão de determinismo chegaria sem o comparador de que depende. São oito commits atômicos dentro de uma mudança coerente, que é o que a RFC pede de um PR.

Plano de Rollback

git revert dos commits deste PR. Não há estado a desfazer: sem migração, sem feature flag, sem configuração. Reverter devolve o repositório ao que era, e o único efeito é o CI voltar a não ter o portão de determinismo.

Referências

• Issue: [FEAT] Comparador de paridade do metrics.json, campo a campo #214
• Desbloqueia [DEBT] Busca de PR: os três estados numa query GraphQL com alias #215, que passa a ter portão de aceite verificável — o critério dela é exatamente metrics.json idêntico campo a campo
• RFC 0016 §5.1 (trunk based), RFC 0028 (padrão de PR), RFC 0029 PM-4 (verificação fora da máquina de quem construiu)
• Precedente de script em CI: scripts/check_analysis_chain.py

Autoria Assistida

• Agente: Claude Code — claude-sonnet-5 nos commits, claude-opus-5 na orquestração e nas revisões
• Escopo da assistência: medição do determinismo do engine que fundamenta a lista de ignorados vazia, desenho do módulo e do CLI, implementação guiada por testes, e as duas correções vindas da revisão de branch inteira (comparação estrita em tipo e códigos de saída do CLI)
• Revisão humana: pendente — o autor revisa antes do merge

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clickbus-iris	Ready	Preview	Sep 15, 2026 5:25pm UTC

[kody-ai]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	❌
Security	✅
Business Logic	✅

Access your configuration settings here.

​

[kody-ai]

flatten_metrics merges children with flat.update(), so two distinct keys that concatenate to the same dotted path (e.g., {"a": {"b.c": 1}} and {"a": {"b": {"c": 1}}}, or sibling keys {"a.b": 1, "a": {"b": 2}}) silently overwrite each other and collapse into one leaf. This causes compare_metrics to report [] — 'metrics.json identical field by field' — despite a payload structure change, producing the exact false negative this PR-fetch-gate exists to catch. Detect the collision during flatten and raise a ValueError naming the colliding raw keys (or return a collision list for the caller to surface) instead of silently keeping the last write.

for key, value in payload.items():
    child = f"{prefix}.{key}" if prefix else str(key)
    child_flat = flatten_metrics(value, child)
    for p in child_flat:
        if p in flat:
            raise ValueError(f"key collision after flattening: {p!r}")
    flat.update(child_flat)

Prompt for LLM

File iris/reports/metrics_diff.py:

Line 67 to 72:

flatten_metrics merges children with flat.update(), so two distinct keys that concatenate to the same dotted path (e.g., {"a": {"b.c": 1}} and {"a": {"b": {"c": 1}}}, or sibling keys {"a.b": 1, "a": {"b": 2}}) silently overwrite each other and collapse into one leaf. This causes compare_metrics to report [] — 'metrics.json identical field by field' — despite a payload structure change, producing the exact false negative this PR-fetch-gate exists to catch. Detect the collision during flatten and raise a ValueError naming the colliding raw keys (or return a collision list for the caller to surface) instead of silently keeping the last write.

Suggested Code:

    for key, value in payload.items():
        child = f"{prefix}.{key}" if prefix else str(key)
        child_flat = flatten_metrics(value, child)
        for p in child_flat:
            if p in flat:
                raise ValueError(f"key collision after flattening: {p!r}")
        flat.update(child_flat)

_{Talk to Kody by mentioning @kody}

_{Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.}

​

​

[kody-ai]

The new parsing/comparison functions (flatten_metrics, path_is_ignored, compare_metrics, format_divergences) lack unit tests, yet they serve as the acceptance criterion for the PR-fetch optimization and rollout parity gate. A regression in recursive flattening, wildcard path matching, or type-strict comparison would silently break field-by-field equality checks. Add a test module (e.g., iris/reports/test_metrics_diff.py) covering flatten_metrics with nested dicts/lists/empty containers and the empty-root edge case; path_is_ignored with single-segment wildcards; compare_metrics type strictness (True vs 1, int vs float), missing keys on each side, and ignored paths; and format_divergences for both empty and non-empty output.

Kody rule violation: Unit test complex pure parsing functions

Prompt for LLM

File iris/reports/metrics_diff.py:

Line 100:

The new parsing/comparison functions (flatten_metrics, path_is_ignored, compare_metrics, format_divergences) lack unit tests, yet they serve as the acceptance criterion for the PR-fetch optimization and rollout parity gate. A regression in recursive flattening, wildcard path matching, or type-strict comparison would silently break field-by-field equality checks. Add a test module (e.g., iris/reports/test_metrics_diff.py) covering flatten_metrics with nested dicts/lists/empty containers and the empty-root edge case; path_is_ignored with single-segment wildcards; compare_metrics type strictness (True vs 1, int vs float), missing keys on each side, and ignored paths; and format_divergences for both empty and non-empty output.

_{Talk to Kody by mentioning @kody}

_{Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.}

​

​