Lodemap
Veja como seu sistema funciona e como sua arquitetura vem mudando. Fluxos, linha do tempo do Git e evidências
locais, em um mapa que vive no seu repositório.
Versão atual: v0.1.0 · Página e vídeo: skarl007.github.io/lodemap · Demo: mapa do axios
O Lodemap oferece observabilidade da arquitetura para pessoas: quem conversa com quem, por onde passa cada fluxo,
o que mudou entre versões do mapa e quais evidências locais estão ligadas a cada componente. O modelo C4 em
Structurizr DSL fica ao lado do código; scripts geram o explorador interativo,
o leitor de documentação e decisões (ADRs), as métricas e as comparações históricas.
O teste de cobertura é a garantia estrutural por trás do acompanhamento: detecta módulos fora do modelo e caminhos
que sumiram, conforme os globs e as exceções do projeto. Ele não garante a verdade de descrições, relações ou status.
O Lodemap não coleta telemetria de execução.
Demonstração ao vivo: o explorador e o
leitor de docs de um mapa do axios
(72 componentes, 7 fluxos animados) que acompanhou cinco releases reais, da v1.17.0 à v1.21.1: cada release virou uma
versão do mapa, comparável na linha do tempo. Páginas estáticas, sem servidor, sem requisição externa.
O mapa original, neste repositório: exemplos/axios/ guarda as fontes do primeiro mapa do
axios, feito na v1.20.0 e atualizado para a v1.21.1, com 6 fluxos (DSL, docs, ADRs, métricas, lodemap.json), cerca de
300 KB, sem página gerada e sem caminho privado. O
tests/test_exemplo_axios.py o regenera de ponta a ponta a partir de uma cópia limpa do axios v1.21.1 com o
Structurizr CLI de verdade, e depois roda os testes que o mapa entrega e o gate de qualidade. O CI roda esse teste
em Linux e macOS. Para regenerar você mesmo:
bash .circleci/preparar_pipeline.sh # Structurizr CLI (sha256 checked) and axios v1.21.1 into ~/axios
LODEMAP_EXEMPLO_AXIOS=~/axios python -m pytest -q tests/test_exemplo_axios.py
Acompanhar a arquitetura
- Fluxos: percorra os passos modelados e veja os componentes e relações envolvidos. São fluxos descritos no
modelo, não rastros de requisições em produção.
- Linha do tempo: abra a visão no explorador, escolha uma versão e compare as entradas, saídas e alterações com
a versão-base registrada. O grafo histórico, as visões e o histórico de cada componente vêm dos snapshots do Git.
“Tocar evolução” percorre as versões disponíveis; o histórico só existe onde o mapa foi versionado.
- Saúde: a cor mostra se testes encontrados referenciam o código, se nenhuma referência foi encontrada ou se
faltam dados. O inspetor apresenta cobertura por arquivo, atividade no Git e falhas de JUnit quando fornecidas.
“Pronto” sem referência estática de teste gera um alerta para revisão, não um diagnóstico de defeito.
- Proveniência: confira a data e o commit da evidência. A árvore de trabalho não é verificada; um commit igual
ao do mapa não prova que testes ou relatórios vieram daquela revisão. A linha do tempo não aplica evidências atuais
aos snapshots históricos.
Os dois coletores rodam localmente sem chamar modelo. A partir da raiz do checkout do Lodemap, use os caminhos do
seu projeto:
python scripts/linha_do_tempo.py --mapa /caminho/projeto/docs/architecture/structurizr --resumo
python scripts/evidencias.py --repositorio /caminho/projeto --mapa /caminho/projeto/docs/architecture/structurizr --json
O primeiro grava explorador/linha-do-tempo.js e .json; o segundo grava explorador/evidencias.js e, com
--json, .json. Relatórios opcionais entram com --cobertura coverage.xml (ou lcov.info) e
--junit junit.xml, relativos à raiz do projeto. Uma referência de teste é estática, não prova execução; o JUnit só
associa casos com atributo file. Os comandos, a atualização da interface e os backups estão em
references/scripts.md.
A demo pública acima é o replay das cinco releases, refeito a partir da v1.17.0; o mapa original de exemplos/axios/
segue como teste de ponta a ponta no CI. O ganho de entendimento humano ainda não foi medido: o estudo está
pré-registrado em experimentos/estudo-pessoas/PROTOCOLO.md e a coleta não
começou.
O gate, numa release real
O mapa foi feito no axios v1.20.0. Depois o upstream lançou a v1.21.1 (99 commits, 27 arquivos alterados em lib/,
três deles novos). Depois de mesclar a tag, o teste de cobertura falhou e apontou os três arquivos. A gravação abaixo
mostra a saída real de cada comando (caminhos longos cortados).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
