Preflight

Uma regra sabe como verificar algo. Sua política decide se ela executa, seus parâmetros, severidade e comportamento de bloqueio. Dois projetos podem usar o mesmo assembly com limites de tamanho diferentes, sem criar forks do código. Isso permite testar a lógica de validação separadamente e alterar requisitos sem recompilar a ferramenta.

{
    "schemaVersion": 1,
    "pipeline": "projecta",
    "rules": {
        "core.presubmit.large-file": {
            "settings": {
                "maxBytes": 5242880
            }
        }
    },
    "targets": {
        "win64": {
            "rules": {
                "core.presubmit.large-file": {
                    "settings": {
                        "maxBytes": 2621440
                    }
                }
            }
        }
    }
}

As regras declaram dependências e executam por níveis topológicos. Verificações independentes compartilham um nível; níveis posteriores aguardam os pré-requisitos. Se a verificação da toolchain falha, uma sonda de compilação dependente pode ser pulada em vez de gerar outra falha previsível.

A atribuição de causa raiz percorre a cadeia de dependências, atravessando skips intermediários. A mensagem final aponta para a toolchain ausente, oferecendo um problema para resolver em vez de uma lista de sintomas. O stage seleciona as raízes desse grafo, sem descartar dependências de outros stages.

Escolhi uma barreira entre níveis para simplificar a propagação de falhas e a coordenação. Uma regra lenta segura o próximo nível, mesmo que parte dele já pudesse começar. Esse custo é uma escolha consciente: a execução é mais simples de auditar, e o relatório é ordenado por nível e ID, independentemente de qual tarefa termina primeiro.

Uma convenção de nomes pode bloquear um submit sem tornar a compilação inútil. Uma sonda opcional pode ser um pré-requisito técnico mesmo quando sua falha não deve reprovar o envio. Um único booleano não expressa os dois casos. Preflight separa blocking, que afeta o resultado e o exit code, de gating, que interrompe regras dependentes. A severidade continua sendo o nível de comunicação, sem substituir essas decisões.

Políticas podem herdar parâmetros, aplicar targets explícitos de plataforma/configuração e selar chaves contra alterações nas camadas posteriores. Os selos se acumulam na cadeia de herança, impedindo um projeto de remover silenciosamente uma restrição da organização. Overlays locais da máquina ficam fora da CI.

O comando explain registra a origem dos valores efetivos, incluindo pacote, arquivo, linha e valores substituídos. Os eixos de target precisam ser informados explicitamente para casar com um bloco. Assim, um default de configuração não escolhe silenciosamente outra política de produção.

A precedência precisa ser visível porque um valor em JSON, sozinho, não explica a configuração efetiva. Sem proveniência, investigar uma diferença entre a máquina local e a CI exigiria reconstruir a herança à mão. O comando preflight explain transforma essa investigação em dados da própria resolução.

Regras implementam IValidationRule usando Preflight.Abstractions. Acesso a arquivos, processos, alterações e política chega pelos serviços de RuleContext, permitindo testar verificações sem o workspace real. O assembly de regras embutidas não tem uma dependência privilegiada de Core.

Plugins carregam em contextos de assembly separados e coletáveis, compartilhando o assembly do contrato com o host. Versões de dependências podem coexistir; IDs duplicados e contratos incompatíveis geram recusas identificadas em vez de um vencedor arbitrário. É isolamento de dependências, não uma sandbox de segurança: os plugins são código confiado por quem publica a pipeline.

Um pacote de pipeline contém política, assemblies de regras e um manifesto com SHA-256 por arquivo e faixa de contrato suportada. Ordem estável das entradas e timestamps fixos tornam os bytes do arquivo reproduzíveis. A instalação verifica o pacote antes de consolidá-lo no armazenamento instalado.

O checkout declara uma faixa de versões aceitas; uma máquina pode fixar uma versão para rollback. Instalar um pacote não altera esse pin. Preflight não busca atualizações sozinho, deixando a distribuição para o canal de artefatos do estúdio e evitando mudanças inesperadas nas regras das máquinas.

Passed, Warning, Failed, Errored, Skipped e NotApplicable têm significados distintos. Uma regra sem algo aplicável para inspecionar não afirma sucesso; uma regra que caiu é diferenciada de um defeito no workspace. Console, JSON e SARIF apresentam os mesmos dados de relatório. Exit codes distinguem uma alteração bloqueada de configuração inválida e erro interno.

O histórico é NDJSON local com escrita append-only; estatísticas de duração aparecem apenas com observações suficientes. A ferramenta pode medir um comando de build, mas medir sua duração não comprova que ele foi validado ou que o software funciona.

O determinismo vale para o veredito e a ordem dos achados quando os inputs são iguais, incluindo o ambiente inspecionado e a versão da pipeline. A duração e o runId variam por construção; comparar relatórios byte a byte exige controlar esses campos. Uma política igual sobre máquinas com SDKs diferentes pode corretamente produzir resultados diferentes.

O cache é opt-in e só atende regras que fornecem um fingerprint explícito dos inputs. A chave também inclui a política efetiva da regra, stage, target, geração do contrato e identidade do assembly. Alterar um limite ou recompilar um plugin invalida o resultado anterior. Resultados de cache são identificados visivelmente, sem apresentar trabalho reutilizado como uma nova verificação.

O custo dessa escolha é exigir que o autor da regra descreva os inputs relevantes. Para uma sonda que não consiga representar seu ambiente com segurança, executar de novo é preferível a reutilizar evidência incompleta. O cache fica desligado por padrão.