diff-sistema

Diff de Sistema (System Diff)

Um diff de sistema mostra o que uma alteração faz no sistema em execução: os componentes e fluxos que adiciona, remove ou altera, os estados pelos quais uma entidade agora pode transitar, os fatos que mudam e a nova forma de falhar. O diff de linhas é a evidência; o diff de sistema é a história que um revisor precisa.

Você modela a alteração como um spec, e o script renderiza o spec como um vídeo em beats: título, um antes e um depois para cada diagrama, falha, encerramento. Abaixo, <script> é o caminho absoluto de scripts/system-diff.mjs na pasta desta habilidade.

1. Verificar setup

Execute node <script> doctor. Ele termina com Pronto. em uma máquina configurada.

Em qualquer outro término, ou quando node estiver ausente, pare e peça ao usuário para executar /setup-system-diff, que instala tudo o que esta habilidade precisa.

2. Coletar a alteração

A alteração é um pull request, um branch ou um intervalo de commits. Se nada for especificado, considere o branch atual contra sua base: a branch base do pull request quando houver uma, caso contrário, a branch padrão do repositório. Pergunte ao usuário quando nenhum dos dois estiver claro.

Trabalhe em um checkout que esteja no head da alteração, porque o passo 4 verifica suas evidências contra os arquivos no disco.

• Leia o diff completo (gh pr diff <número>, ou git diff <base>...<head>), e a descrição do pull request quando houver uma, ou as mensagens de commit quando não houver.
• Para cada hunk que toque em uma chamada, uma consulta, um agendamento, um valor de configuração, um esquema ou uma permissão, leia código suficiente ao redor dele, na base e no head, para saber quem chama quem em tempo de execução.

Concluído quando você puder dizer, para a base e para o head: o que executa, com o que cada coisa se comunica, o que armazena e o que acontece quando cada coisa da qual depende está fora do ar.

3. Modelar a alteração no sistema

Liste a alteração como claims (afirmações), cada uma com o caminho:linha que a mostra. As claims se tornam o spec no passo 4 e vão para o usuário no passo 6.

• Componentes: coisas que executam ou armazenam dados, como um serviço, um job, uma fila, uma tabela ou uma API externa. Inclua os inalterados que um visualizador precisa para acompanhar o fluxo.
• Fluxos: um componente chamando, lendo ou escrevendo em outro.
• Estados e transições: os estágios pelos quais uma entidade percorre, como um pedido, um job, uma sessão ou uma conexão, e os eventos que a movem de um para o próximo.
• Fatos: um aspecto do sistema com um valor antes e depois, como um valor de configuração, um limite, um esquema, quem pode fazer o quê, ou quanto tempo algo leva.
• Modo de falha: a nova maneira mais importante de falhar. Geralmente um novo componente ou nova dependência para de funcionar; também pode ser um existente cuja falha agora custa mais, ou um estado no qual uma entidade pode agora ficar presa. Diga o que acontece então: o que cada outro componente faz, ou onde a entidade acaba.

Cada claim cita a linha que a mostra. Uma claim sem linha para citar é um palpite e fica de fora do vídeo.

Algumas alterações deixam o sistema como estava: uma refatoração, formatação, testes, comentários, uma renomeação de algo que apenas o código vê. Para estas, diga ao usuário que a alteração não tem diff de sistema e que tipo de alteração é, e termine aí sem vídeo. Uma renomeação de algo que o sistema em execução vê, como uma rota, uma tabela, uma fila ou uma chave de configuração, é uma alteração de sistema.

As claims decidem qual diagrama o vídeo desenha:

• Visão de componentes, quando a fiação (wiring) muda: um componente ou um fluxo é adicionado ou removido, ou um fluxo carrega algo diferente.
• Diagrama de estados (statechart), quando um ciclo de vida muda: um status ganha ou perde um valor, uma etapa de retry ou cancelamento aparece, ou um evento agora leva a outro lugar.
• Um valor que muda enquanto a fiação e o ciclo de vida permanecem os mesmos, como um timeout maior, é um fato, mostrado sob o diagrama que lhe dá contexto.
• Ambos, quando ambos mudam e cada um mostra algo que o outro não pode. Cada diagrama adiciona dois beats, então uma alteração que um diagrama conta por completo fica com um.

Concluído quando cada hunk do diff é coberto por uma claim ou deixado de lado como inalterado no sistema, e você escolheu os diagramas.

4. Escrever o spec

Transforme as claims em um spec, seguindo o SPEC.md, que tem todos os campos, as regras de layout e como escrever as legendas e narração. Salve-o como system-diff.json em uma pasta temporária fora do repositório.

Execute node <script> check <spec> --repo <raiz do repositório>.

Concluído quando ele imprimir exatamente O spec é válido., sem avisos. check confirma que cada linha citada existe; que a linha mostra a claim é sua responsabilidade confirmar.

5. Construir e ler a folha de contato

Execute node <script> build <spec> --repo <raiz do repositório> --out <pasta temporária>. Ele imprime o caminho do vídeo, seus avisos, uma folha de contato (uma imagem com um quadro de cada beat) e uma pasta stills contendo os mesmos quadros em tamanho real.

Leia a folha de contato para a visão geral e os stills para o texto pequeno, e verifique cada quadro:

• cada rótulo, valor e legenda está completo e legível;
• cada linha de fluxo passa clara das caixas e rótulos que não conecta;
• cada quadro "antes" mostra apenas o que existia antes, e cada quadro "depois" mostra tudo o que a alteração adicionou;
• o ponto inicial do statechart está no estado em que a entidade começa;
• o quadro de falha marca o componente ou estado correto, e cada nota está na borda inferior daquela que descreve;
• cada legenda diz o que seu quadro mostra.

Corrija o spec e construa novamente até que a construção imprima Sem avisos. e a folha passe em todas as verificações. A maioria dos problemas de quadro cede a texto mais curto ou a mover uma caixa para outra célula. Um que sobreviva a ambos vai para o hand-over (entrega), nomeado.

6. Entregar

Forneça ao usuário o caminho do vídeo, uma frase sobre o que ele mostra, as claims com suas evidências e qualquer coisa que você tenha deixado de fora ou sobre a qual não tenha certeza. Publicar o vídeo em qualquer lugar é decisão do usuário.