Validação e relatórios

validate-project-structure é a porta determinística para geração e projetos ContractForge escritos à mão. Ele valida o formato do projeto e pode perguntar adaptadores instalados para planejar os contratos sem executar o código da plataforma.

Validar uma pasta de projeto

contractforge-ai validate-project-structure generated/supabase \
  --adapter databricks \
  --adapter aws \
  --format html > generated/supabase/project_validation.html

O validador verifica:

• project.yaml;
• referenced environment YAMLs;
• referenced shared connection YAMLs;
• pacotes de ingestão e anotações/operações/arquivos de acesso irmãos;
• herança de conexão e substituições no nível de ingestão;
• cron e fuso horário do cronograma do projeto;
• status do planejador do adaptador, avisos e bloqueadores.

Output formats

Format	Usar
text	Local terminal checks.
json	Portas CI e automação.
markdown	Pull-request comments.
html	Revisão humana, capturas de tela e transferência de projetos.

HTML é o formato de revisão preferido porque projetos reais têm caminhos longos, códigos de aviso do adaptador e cargas úteis do planejador. O relatório apresenta resultados e evidências do adaptador como cartões em vez de forçá-las em colunas estreitas da tabela.

Status mapping

Status	Ready	Meaning
READY	true	Sem bloqueadores determinísticos ou avisos de adaptador.
READY_WITH_WARNINGS	true	Only reviewable warnings remain.
NEEDS_DECISIONS	false	As decisões humanas permanecem antes da implantação.
INVALID	false	A estrutura do projeto, o carregamento do pacote configurável ou o planejamento do adaptador falharam.
UNSAFE	false	Foram encontrados segredos embutidos ou entradas de projeto inseguras.

Os avisos do adaptador não se tornam um sucesso silencioso. Eles permanecem visíveis no report, but warning-only projects remain ready=true.

Validação com reconhecimento de adaptador

A validação com reconhecimento de adaptador chama apenas APIs de planejamento público:

Adaptador	Planner
Databricks	plan_databricks_contract
AWS	plan_aws_contract

Não:

• create Databricks jobs;
• call AWS Glue APIs;
• implantar infraestrutura;
• executar ingestão;
• resolve secret values.

Exemplos reais

Valide o projeto USGS REST/GeoJSON:

contractforge-ai validate-project-structure examples/real-world/usgs-earthquake-rest-medallion \
  --adapter databricks \
  --adapter aws \
  --adapter snowflake \
  --adapter fabric \
  --adapter gcp \
  --format html > usgs-project-validation.html

Interpretação esperada:

• Os contratos adaptadores devem ser planejados conforme suportados quando a semântica estiver dentro do superfície estável documentada.
• Um projeto pode incluir avisos de adaptador quando uma plataforma requer um tempo de execução pré-requisito ou um limite de revisão explícito.
• O projeto pode ser READY_WITH_WARNINGS quando não houver valores críticos ou altos findings.

A saída do provedor não pode substituir a validação

Se um provedor disser "pronto" enquanto a validação determinística disser NEEDS_DECISIONS, INVALID ou UNSAFE, a saída do provedor está errada. O validator remains authoritative.

Use validate-artifact para saída do modelo gerado:

contractforge-ai validate-artifact \
  --model-output provider-output.json \
  --prompt project.spec.enrichment.v1 \
  --fallback deterministic-spec.json \
  --format html > provider_validation.html