Referência da linha de comando

Sinopse

probe init [--repo PATH] [--language go|typescript|javascript|python|rust]
probe lint [--base main] [--head HEAD] [--ci] [flags]
probe review [--base main] [--reviewer=false] [--ci] [flags]
probe review [flags] BASE..HEAD
probe plan --intent-file FILE [--base main] [--ci]
probe review --plan .probe/PLAN.json [flags]
probe report [--input .probe/confidence-report.json] [--out DIR] [--format LIST] [--report-url URL]
probe version

• lint analisa uma mudança de forma estática. Ele nunca executa código do repositório e nunca chama um provedor de IA.
• review acrescenta verificações em sandbox no Docker, as etapas opcionais de evidência (testes da baseline alterados, testes impactados, fuzzing diferencial, mutação, preparação de dependências) e, quando um modelo está configurado, uma investigação por IA.
• plan pede ao provedor configurado um plano de implementação antes de qualquer código ser escrito, avalia-o com regras fixas e o transforma em um contrato com o qual lint --plan e review --plan comparam o diff.
• Somente arquivos commitados são analisados; edições não commitadas e arquivos não rastreados são ignorados.
• Por padrão, os relatórios são gravados em .probe/ no repositório. A saída do console continua curta.
• As flags aceitam um ou dois hífens (-ci ou --ci). Booleanos são ativados com --ci ou --ci=true e desativados com --checks=false. Um valor é informado como --base main ou --base=main.
• Execute probe <command> --help para ver as flags de um comando.

Escolhendo revisões

Os dois lados de uma comparação são resolvidos em IDs de commit imutáveis, registrados no relatório. Renomeações, exclusões, arquivos binários e mudanças de tipo de arquivo são tratados.

Um intervalo pode aparecer antes ou depois das flags: probe review main..HEAD --ci e probe review --ci main..HEAD são equivalentes. No máximo um intervalo é aceito. Qualquer revisão que o Git entenda funciona: branches, tags, origin/main, HEAD~3 ou um ID de commit. Os jobs de CI precisam de histórico suficiente para resolver a base (por exemplo fetch-depth: 0).

A política confiável é sempre lida da branch base, nunca da mudança em revisão, então um pull request não consegue afrouxar as próprias regras.

probe lint

Análise estática de uma mudança: comparação Git, sinais de risco e um relatório. Sem Docker, sem chamada a provedor, sem execução de código do repositório. Seguro para rodar em branches não confiáveis.

probe lint HEAD~1..HEAD                 # the last commit
probe lint --base origin/main --ci      # this branch as a pull request, for CI
probe lint --base main --format json    # JSON report only
probe lint --base main --plan .probe/PLAN.json   # scope drift against an approved plan

probe review

Tudo o que o lint faz, mais os comandos test, typecheck, build e coverage da política em contêineres Docker descartáveis, mais uma investigação por IA quando um modelo está configurado. Exige Docker com contêineres Linux e uma sandbox.image pré-carregada.

probe review --base main --ci                        # typical pull request run
probe review HEAD~1..HEAD --reviewer=false           # checks only, no provider
probe review --base main --checks=false --reviewer=false   # static only, like lint
probe review --base main --intent-file PR.md         # give acceptance criteria
probe review --base main --impacted-tests --base-tests --ci   # run tests on both revisions
probe review --base main --format markdown,json,sarif,pr-comment --report-url "$RUN_URL"

A preparação de dependências roda primeiro, quando a política tem um objeto prepare. Em seguida, as verificações rodam na ordem test, typecheck, build e depois coverage, seguidas pelas etapas de evidência e pelo revisor. Cada contêiner roda sem root, com raiz e montagem do código-fonte somente leitura, sem capabilities adicionais, sem rede por padrão e com os limites de CPU, memória, PIDs e tempo da política de sandbox. O socket do Docker, o seu checkout de trabalho e as chaves de API nunca são montados. Se o Docker ou a imagem estiverem ausentes, a execução termina com saída 4; nada jamais recorre à sua máquina.

probe plan

Antes de a mudança ser escrita: o provedor configurado simula, em modo somente leitura, como implementaria uma intenção no commit base e envia um plano estruturado (arquivos, símbolos, dependências, etapas). O Probe o avalia com regras fixas e grava PLAN.json e PLAN.md. O modelo produz o plano; ele nunca julga o risco. Nada é modificado nem executado.

As ferramentas do planejador são somente leitura e trabalham sobre um snapshot do commit base: list_files, read_file, search_code e as baseadas no índice find_references, inspect_symbol e find_callers, e então submit_plan uma única vez. A avaliação sinaliza quatro categorias, considerando apenas o plano e o commit base:

Códigos de saída: 0; 2 com --ci quando uma categoria é sinalizada; 3 uso ou configuração; 4 falha do provedor ou nenhum plano aceito.

Desvio de escopo: --plan

lint --plan e review --plan leem o contrato do plano e comparam o diff real com ele. Cada diferença no diff também vira um sinal plan_drift. A seção fica drifted quando um item é de gravidade média ou maior.

probe plan --intent-file task.md --ci                     # 1. plan; exit 2: a human validates it
# 2. an agent implements the plan
probe review --base origin/main --plan .probe/PLAN.json --ci   # 3-4. exit 0: merge; exit 2: review

O plan gate

review --plan termina com uma decisão, plan_drift.decision, impressa no stdout e no topo da seção Plan Conformance. Com --ci, ela é o código de saída.

As flags e o contrato armazenados em PLAN.json nunca são considerados confiáveis: o contrato é derivado novamente da proposta, então um plano editado não consegue ampliar o escopo sem avaliação, e probe report recalcula a decisão a partir do relatório registrado. O gate é uma decisão de processo, não um veredito sobre a correção. Um plano que não levanta nada não prova que a mudança é segura, e o desvio não verifica se a mudança implementa a intenção. Veja planos pré-mudança e a receita de CI.

probe init

Grava um .probe.json inicial para o projeto. Ele se recusa a sobrescrever um arquivo existente. Revise os comandos e a imagem e depois faça commit do arquivo na sua branch base.

probe report

Renderiza novamente um relatório JSON salvo, por exemplo para regenerar o Markdown ou produzir SARIF no CI. Nada é executado de novo, e a nova renderização não autentica as evidências que o relatório contém; cada status é derivado novamente das verificações registradas, então um relatório editado é corrigido em vez de ser considerado confiável.

probe version e ajuda

Códigos de saída

Nenhum código significa "aprovado". Um 0 diz que nada foi reproduzido, não que a mudança está correta.

Variáveis de ambiente

O provedor de IA pertence à implantação, e não ao repositório, então essas configurações podem vir do ambiente. Nada mais pode: a imagem, os comandos, os orçamentos e os caminhos sensíveis são sempre decididos pela política confiável.

Uma variável em branco conta como não definida. Os arquivos de chave são lidos inteiros, com os espaços ao redor removidos, limitados a 8 KiB, e devem conter uma única linha. Quando o revisor roda, o log indica de onde veio cada valor, nunca o próprio valor. Quem controla este ambiente escolhe para onde o código-fonte com dados ocultados é enviado: mantenha-o fora de jobs que executam código de forks não confiáveis.

Arquivos de saída

Adicione .probe/ ao .gitignore. O console exibe um único resumo: arquivos e linhas alterados, número de sinais e de problemas reproduzidos, a superfície de revisão focada e a execução das linhas alteradas.

Sinais de risco

Sinais são motivos para olhar, não defeitos confirmados. Arquivos Go recebem análise sensível à sintaxe; TypeScript/JavaScript, Python, Rust e outras linguagens usam heurísticas de texto identificadas como tal. Sinais nas mesmas linhas são mesclados em um único intervalo de revisão no relatório. Sinais de nível de arquivo (sensitive_path, dependency_change, migration_change, infrastructure_change, binary_change, file_deleted, file_type_change, large_change, branch_growth, no_test_change, prepare_input_changed, plan_drift) dizem respeito ao arquivo, não a uma linha: o relatório os lista sob o arquivo como arquivo inteiro, e o JSON os marca com "scope": "file". A line deles apenas os posiciona na primeira linha alterada do arquivo.

Análise de impacto

Com --impact (o padrão), lint e review constroem um índice estático do commit candidato na máquina host, a partir dos objetos Git commitados, sem executar código do repositório. Para cada função alterada, ele lista os pontos do código não alterado que a chamam e os testes existentes que a alcançam em até 3 chamadas, adiciona sinais impacted_caller de gravidade baixa e dá suporte às ferramentas find_references, inspect_symbol e find_callers do revisor.

Toda resposta é aproximada: um chamador listado é um ponto a revisar, e a ausência de chamadores não prova que não exista nenhum. --impacted-tests executa apenas os testes Go que alcançam a função. Veja análise de impacto.

Linguagens

Arquivo de política: .probe.json

A política decide quais comandos rodam, em qual imagem, com quais limites e se um provedor de IA é usado. Ela é lida do .probe.json na branch base ou de --config PATH. Quando não há nenhuma, aplicam-se os padrões embutidos da linguagem detectada. As chaves omitidas assumem os valores padrão mostrados abaixo.

O arquivo deve ser um único objeto JSON de no máximo 1 MiB. Chaves desconhecidas, nomes de comando desconhecidos e chaves duplicadas são rejeitados com saída 3, então um binário mais antigo rejeita uma chave que não conhece.

{
  "version": 1,
  "language": "go",
  "commands": {
    "test": ["go", "test", "./..."],
    "typecheck": ["go", "vet", "./..."],
    "build": ["go", "build", "./..."],
    "generated_test": ["go", "test", "{package}"],
    "coverage": ["go", "test", "-covermode=count", "-coverprofile={coverage_out}", "./..."]
  },
  "sandbox": { "image": "golang:1.26-bookworm", "network": false, "timeout_seconds": 120,
               "max_runtime_seconds": 600, "max_output_bytes": 65536, "memory_mb": 1024, "cpus": 2 },
  "reviewer": { "endpoint": "https://api.openai.com/v1/chat/completions", "model": "",
                "api_key_env": "PROBE_API_KEY", "max_iterations": 20, "max_generated_tests": 10,
                "timeout_seconds": 600, "max_input_bytes": 131072 },
  "sensitive_paths": ["**/auth/**", "**/payment*/**", "**/migrations/**", ".github/workflows/**", ".probe.json"]
}

commands

Cada comando é um array argv, não uma string de shell: ["npm", "test"], nunca "npm test". No máximo 128 argumentos; configure apenas as verificações que o seu projeto oferece.

sandbox

reviewer

sensitive_paths

Globs de caminhos que sempre geram um sinal sensitive_path de gravidade alta quando alterados. Os caminhos são relativos à raiz do repositório, com barras normais; * corresponde dentro de um segmento do caminho e ** atravessa segmentos. Caminhos absolutos, barras invertidas e .. são rejeitados.

fuzz v0.4

Passa as mesmas entradas geradas a partir de uma seed por cada função Go de nível de pacote alterada e cada função TS/JS exportada alterada (com assinatura inalterada), na baseline e na candidata, e compara o que as duas revisões registraram. Uma função diverged é uma observação, nunca um defeito: ela pede revisão (saída 2 com --ci) e nunca produz saída 1. {} a ativa com os padrões.

mutation v0.4

Faz pequenas mudanças determinísticas nas linhas adicionadas de arquivos Go alterados que não são de teste e executa os testes do pacote uma vez por mutante. Um mutante que nenhum teste percebe vira um sinal surviving_mutant de gravidade média; nenhuma pontuação é calculada. As quatro chaves são obrigatórias.

"mutation": {
  "command": ["go", "test", "-json", "-count=1", "-failfast", "{package}"],
  "max_mutants": 20, "timeout_seconds": 60, "max_runtime_seconds": 300
}

prepare v0.4

Permite que a política confiável da branch base construa a camada de dependências: antes de qualquer código candidato rodar, o comando dela roda uma vez, em um único contêiner com limites, sobre os arquivos de dependências exportados do commit base, e o contêiner vira a imagem local de todas as verificações. Um review posterior com a mesma base e as mesmas entradas a reutiliza. Quando nenhuma imagem é produzida, o review sai com 4; ele nunca recorre à imagem não preparada.

"prepare": { "command": ["go", "mod", "download"], "inputs": ["go.mod", "go.sum"], "network": true }

Padrões por linguagem

Gravados pelo probe init e usados quando a branch base não tem política. As imagens padrão de Node.js, Python e Rust não contêm as suas dependências: construa uma imagem que as contenha, ou adicione um objeto prepare, e adapte os comandos.

Revisor de IA

Opcional. Quando um modelo está configurado, o review permite que ele investigue a mudança com ferramentas limitadas: ler arquivos e diffs com dados ocultados, pesquisar o código-fonte, consultar referências e chamadores no índice estático, executar as verificações existentes e criar e executar testes temporários na base e na candidata. Ele não tem shell nem acesso a URLs. As afirmações dele continuam sendo hipóteses até que um teste reproduza uma diferença.

{
  "reviewer": {
    "endpoint": "https://your-provider.example/v1",
    "model": "your-tool-capable-model",
    "api_key_env": "PROBE_API_KEY"
  }
}

export PROBE_API_KEY=…                       # from your shell or CI secret store
probe review --base main --config .probe.json   # try it before committing
probe review --base main --reviewer=false            # turn it off for one run

• Somente a política confiável, --config ou o ambiente de implantação podem ativar o revisor; um pull request não pode.
• Um contexto de código-fonte limitado e com dados ocultados é enviado ao provedor. O mascaramento de segredos é feito na base do melhor esforço; use um provedor local (por exemplo http://127.0.0.1:1234/v1) se o código-fonte precisar ficar local.
• As chaves de API nunca entram nos contêineres de teste. O lint nunca chama um provedor.
• Falhas do provedor e orçamentos esgotados preservam os resultados determinísticos e marcam a investigação como incompleta; com --ci, isso exige revisão humana.