Arquitetura do núcleo do BeeverForge

Princípios do repositório

As regras que o repositório do núcleo impõe a si mesmo, de como um teste é nomeado a como uma versão é publicada. A maioria está escrita em CONTRIBUTING.md e docs/RELEASING.md e é garantida por um teste ou por um workflow; quando uma regra é uma convenção e não uma verificação, esta página informa isso.

Testes#

Nomeados como frases#

Um arquivo de teste diz o que prova, por exemplo test_a_card_is_closed_only_when_its_work_merges.py, para que buscar um comportamento na suíte encontre o teste que o garante.

Nas duas ordens e em paralelo#

A suíte roda em ordem aleatória por padrão (pytest-randomly) e em paralelo (pytest-xdist). Quem contribui deve rodá-la em paralelo tanto em ordem aleatória quanto em ordem fixa (-p no:randomly). Uma falha que depende da ordem é tratada como vazamento de estado, não como instabilidade. A CI roda a ordem aleatória, dividida em partes; ela não roda a ordem fixa. O conftest registra a semente de cada execução para que uma ordem possa ser reproduzida.

Guardas provadas por mutação#

tools/mutate.py executa um plano de mutação: cada plano nomeia um teste e uma lista de edições exatas do código, e cada edição precisa deixar esse teste vermelho. Ele se recusa a começar a menos que a âncora de cada edição corresponda exatamente uma vez e a linha de base esteja verde.

• O executor é seguro contra falhas. Antes de mutar um arquivo, ele faz uma cópia fora da árvore e grava uma nota de operação em andamento na raiz do repositório; restaura o arquivo e verifica o texto restaurado em um bloco finally. Como um processo encerrado à força pula o finally, a próxima execução se recusa a começar enquanto existir uma nota e imprime os comandos que restauram o arquivo.
• Os planos de mutação são executados por quem contribui, não pela CI. Um teste verifica que cada plano pode ser executado.

Uma guarda lê a coisa, não um texto sobre a coisa#

Um teste que protege uma configuração a executa ou a analisa: executa o script e lê seus argumentos, ou carrega o YAML e lê a chave. Quando é preciso buscar em texto, os comentários são removidos antes.

Uma suíte hermética#

• As credenciais reais são removidas do ambiente antes da coleta e de novo antes de cada teste: variáveis da plataforma Git, do chat, do motor, do harness e da nuvem, e as configurações BEEVERFORGE_* do próprio operador.
• A suíte roda com seu próprio HOME, com um novo para cada teste, e com o login do gh oculto. O registro de projetos é um diretório temporário, novo para cada teste.
• Nenhum teste alcança um motor real: conectar ao Temporal lança um erro, exceto nos testes marcados owns_its_engine, que iniciam e descartam seu próprio servidor efêmero.
• A suíte faz commits com sua própria identidade de git.

Dependências externas opcionais são puladas em tempo de execução#

A falta de uma ferramenta opcional, como Docker ou node, faz um teste ser pulado ao rodar; isso nunca muda o que é coletado. A CI define TEST_REQUIRE_DOCKER, que lá transforma o pulo por falta de Docker em falha. O servidor de testes do Temporal é um pré-requisito obrigatório, não um pulo.

A CI segue o Makefile e cada teste roda uma vez#

• Cada etapa da CI que testa ou analisa executa um alvo do make (install, lint, test-collect, test-unit em quatro partes, test-integration, test-alone, test-ran-once). As demais etapas obtêm o código, preparam as ferramentas, movem artefatos entre jobs ou informam se todos os jobs passaram.
• Uma guarda expande com make -n os alvos que a CI nomeia e verifica que eles continuam rodando a suíte e analisando cada raiz que a suíte cobre. Nenhuma guarda proíbe uma etapa de CI que não seja um alvo do make.
• A suíte é coletada uma vez; cada parte registra os ids dos testes que executou; scripts/every_test_ran_once.py falha diante de um teste ausente, duplicado ou desconhecido. Uma coleta vazia é uma falha, não um sucesso.

Linters e verificação de tipos#

make lint executa ruff e shellcheck. mypy e bandit estão configurados em pyproject.toml e são instalados com o extra de desenvolvimento, mas nenhum deles roda no Makefile nem na CI; eles não são obrigatórios.

Código e documentação#

Dessas três regras, só o fragmento do changelog é verificado, por um workflow. As outras duas são convenções documentadas, em CONTRIBUTING.md e docs/adr/README.md.

• Os comentários dizem por quê, com a medição: a data, o código de saída ou o incidente que tornou a linha necessária.
• Fragmentos do changelog. Um pull request que muda comportamento adiciona changes/<issue>.<type>.md, onde o tipo é um entre highlight, behaviour, fix, security, upgrade ou limitation. Um workflow verifica cada pull request; um que só muda documentação ou testes leva, em vez disso, o rótulo no-release-note.
• Os registros de decisão são alterados no próprio arquivo. Quando uma decisão muda, o ADR é editado com uma nota datada que nomeia o pull request. Um novo ADR substitui um antigo só quando a decisão é revertida, não quando é refinada.

Lançamentos e versões#

Estas regras são convenções documentadas, escritas em docs/RELEASING.md. O workflow de publicação roda com qualquer tag que comece com v e não as verifica, e o ensaio de instalação roda depois da publicação, não antes. O que é verificado está em Guardas de publicação.

• As versões são versões semânticas anteriores à 1.0. Uma versão menor traz funcionalidades e mudanças de comportamento; um patch traz só correções e recebe a tag no seu branch release/x.y, nunca no main.
• Uma versão candidata recebe a tag vx.y.z-rc.N e é publicada como pré-lançamento; as instalações continuam resolvendo a última versão final, a menos que a candidata seja nomeada. Uma versão menor sempre passa por pelo menos uma candidata.
• O pacote declara exatamente a tag sem o v, e, quando a publicação no PyPI está habilitada, o workflow de publicação recusa uma tag que o pacote não declara. Cada mudança de versão regenera a descrição OpenAPI versionada no mesmo commit.
• A versão final recebe a tag no commit em que a última candidata foi verificada, mais o commit que declara a versão e suas notas.
• Uma versão publicada fica congelada: nenhuma tag é movida, apagada ou enviada de novo. O upgrade deve ser ensaiado antes de cada tag. Defeitos de segurança seguem um caminho de aviso privado. Só o responsável pelas versões cria um branch de versão ou uma tag.

Guardas de publicação#

• O wheel. Um teste constrói um wheel real a partir de uma cópia limpa da árvore e verifica que ele inclui LICENSE e NOTICE, que seu único script de console é beeverforge, que sua descrição longa é a página declarada e que contém todos os arquivos de dados de que a plataforma precisa em tempo de execução.
• A descrição da API. docs/reference/openapi.json precisa ser igual ao que a aplicação gera.

Licença e nome#

O núcleo é licenciado sob Apache-2.0. Não há acordo de licença de contribuidor: a licença já define o que acontece com uma contribuição, e os direitos autorais continuam com quem a escreveu. O arquivo NOTICE separa o código do nome: a licença não concede nenhum direito sobre o nome, o logotipo ou as marcas BeeverForge, e só os builds aprovados na suíte de conformidade publicada (beeverforge conformance, beeverforge conformance-adapter) podem se chamar BeeverForge.

Registros de decisão de arquitetura#

A coluna de status reflete o código no commit fixado. Quando a linha de status do próprio registro e o código divergem, vale o código: “implementado em parte” significa que parte da decisão está no código e parte não.