Solução de problemas

O que cada falha significa, o que verificar e qual o próximo passo seguro.

Comece pelo código de saída

Todo comando termina com um de seis códigos, e o código já estreita o problema antes de você ler qualquer outra coisa.

0   sucesso
1   erro de validação      o arquivo está bem formado, mas viola uma regra
2   estrutura inválida     o workspace não corresponde à especificação
3   desvio detectado       a especificação mudou desde o .orv.lock
4   erro de arquivo        arquivo ausente, vazio ou ilegível
5   erro interno           um defeito no engine

Um caso não vem do engine. Um comando chamado sem um argumento obrigatório — orvienm verify, orvienm new orvienm init sem nada depois — é rejeitado pelo parser de argumentos, que imprime usage: e o nome do argumento que falta, e então sai com 2, como as ferramentas de linha de comando costumam fazer. É um erro de uso, não uma afirmação sobre um workspace: leia a primeira linha da saída para distinguir os dois.

Dois comandos apenas reportam por padrão, em vez de falhar: policy doctor saem ambos com 0 enquanto imprimem o que encontraram. Passe --strict a qualquer um deles para transformar o mesmo achado em saída 2. A detecção é idêntica nos dois modos — só o código de saída muda — então uma etapa que você acrescenta a um pipeline não começa a quebrá-lo sem que você peça.

Leitura do arquivo

File not found: structure.yaml

saída: 4

Significado: O caminho passado ao comando não existe. Nada foi lido e nada foi alterado.
O que verificar: O nome de arquivo padrão do engine é .orvienm.yaml, não structure.yaml nem example.yaml. Confirme o nome do arquivo e se você está no diretório que imagina.
Próximo passo: Passe o caminho correto, ou omita o argumento em plan, apply, graph e policy para deixar o engine encontrar .orvienm.yaml, orvienm.yaml ou orvienm.yml.

Error: Invalid YAML format: mapping values are not allowed here

saída: 4

Significado: O arquivo não pôde ser interpretado como YAML. Isso acontece antes de qualquer regra do Orvienm ser aplicada, então a mensagem vem do parser YAML e inclui linha e coluna.
O que verificar: Indentação, dois-pontos faltando, colchete não fechado ou um caractere de tabulação onde se esperam espaços.
Próximo passo: Corrija a sintaxe na linha indicada e rode o validate de novo.

Error: YAML file is empty. / Root YAML structure must be a dictionary.

saída: 4

Significado: O arquivo foi interpretado, mas o nível superior não é um mapping — ele está vazio, ou é uma lista, ou um escalar solto.
O que verificar: Se o arquivo começa com chaves como version: e structure:.
Próximo passo: Parta do arquivo mínimo da Referência da especificação.

Erros de validação

A validação junta todos os problemas e os reporta de uma vez, um por linha, sob um cabeçalho Validation failed:. As mensagens nomeiam o campo e a falha; elas não trazem número de linha, então localize o campo pelo nome.

Unknown field at root level: 'relationships'.

saída: 1

Significado: O conjunto de chaves de raiz é fechado. Só version, structure, style e policy são aceitas, e qualquer outra é rejeitada em vez de ignorada.
O que verificar: Chaves herdadas de rascunhos antigos ou de outra ferramenta. relationships, requires, profiles e appendix são todas rejeitadas.
Próximo passo: Remova a chave. Se você precisa do que ela expressava, isso não está implementado neste Alpha.

Missing required field 'version'. / Missing required field 'structure'. / Missing required field 'structure.name'.

saída: 1

Significado: Uma chave obrigatória está ausente.
O que verificar: version e structure na raiz; name e directories dentro de structure.
Próximo passo: Acrescente a chave que falta. A validação reporta todos os problemas de uma vez, então uma execução mostra todos eles.

'structure.directories' must be a list. / 'structure.directories' cannot be empty.

saída: 1

Significado: directories está presente mas não é uma lista YAML não vazia. Uma causa comum é escrevê-la como um mapping aninhado.
O que verificar: Se cada diretório é um item de lista sob directories:, e não uma chave indentada.
Próximo passo: Converta mappings aninhados em uma lista plana. Sintaxe de mapping aninhado não é suportada.

Directory '/data' cannot be an absolute path.

saída: 1

Significado: As entradas precisam ser relativas. Uma especificação não pode alcançar fora do workspace.
O que verificar: Barras iniciais e letras de unidade do Windows, como C:\data.
Próximo passo: Expresse o caminho relativo a structure.name.

Directory '../up' cannot contain path traversal ('..').

saída: 1

Significado: A travessia é rejeitada, pelo mesmo motivo de contenção.
O que verificar: Qualquer segmento .. em qualquer ponto da entrada.
Próximo passo: Se o diretório realmente pertence a outro lugar, ele pertence a outra especificação.

Duplicate directory paths are not allowed.

saída: 1

Significado: Duas entradas normalizam para o mesmo caminho. Elas não precisam parecer idênticas — a e ./a colidem, assim como docs e docs/.
O que verificar: Entradas que diferem apenas por um prefixo ./, uma barra final ou o estilo de separador.
Próximo passo: Remova uma delas.

Directory name 'a:b' contains invalid character ':'.

saída: 1

Significado: Os caracteres < > : " \ | ? * são rejeitados em entradas de diretório. Barras são permitidas.
O que verificar: Dois-pontos em especial, que o YAML também trata de forma especial.
Próximo passo: Renomeie o diretório.

Planejamento, aplicação e verificação

Drift detected — Current YAML fingerprint differs from .orv.lock.

saída: 3

Significado: O apply é bloqueado por desvio. A especificação mudou desde que o lock file foi escrito, então o apply se recusa a rodar. Nada foi modificado.
O que verificar: Se a mudança na especificação é intencional. Note que desvio aqui significa que o arquivo mudou, não o sistema de arquivos — editar version, style, structure.name ou a lista de diretórios altera o fingerprint.
Próximo passo: Se a mudança é intencional, apague .orv.lock e aplique de novo; o apply cria o que a mudança acrescentou, mantém tudo o que já estava lá, e um novo lock é escrito. Remover o lock aceita todas as edições do arquivo de uma vez, então leia a especificação antes. Para pré-visualizar sem mexer no bloqueio, use apply --dry-run.

O plan imprime '? undeclared build/' e uma contagem Undeclared diferente de zero.

saída: 0

Significado: O plan encontrou um diretório que a especificação não declara. Ele está reportando, não agendando: o apply não tem caminho de exclusão e não vai removê-lo.
O que verificar: Se o diretório deveria ser declarado. Saídas de build, ambientes virtuais e diretórios temporários costumam aparecer aqui.
Próximo passo: Acrescente-o a directories se ele pertence à estrutura, ou deixe como está — é seguro dos dois jeitos. Nada o remove.

Um diretório adicionado à especificação não foi criado pelo apply.

saída: 3

Significado: O apply faz crescer uma estrutura existente, então um diretório recém-declarado é criado normalmente. O que o impede é o bloqueio por desvio: editar a especificação mudou o fingerprint dela, então o apply saiu com 3 sem tocar em nada. O plan continua reportando '+ create' para a entrada porque o plan é somente leitura e não é bloqueado.
O que verificar: Se o apply imprimiu 'Drift detected' e saiu com 3, em vez de reportar a estrutura como conforme.
Próximo passo: Se a mudança é intencional, apague .orv.lock e aplique de novo. O apply então cria o novo diretório, mantém tudo o que já estava lá e escreve um novo lock. Builds anteriores do Alpha não conseguiam fazer isso — o apply saía com 2 e 'Existing structure is INVALID' mesmo depois de o lock ser removido.

O apply sai com 2 e imprime 'Error while creating structure'.

saída: 2

Significado: Um arquivo já ocupa um caminho que a especificação declara como diretório — seja uma entrada declarada, seja um intermediário implicado por uma entrada aninhada. O apply verifica isso antes de tocar o disco, então nada foi criado: nenhuma árvore parcial fica para trás.
O que verificar: Os caminhos listados sob 'A file already occupies a path the specification declares as a directory'. Cada um é um arquivo parado onde um diretório é declarado.
Próximo passo: Renomeie ou mova o arquivo e aplique de novo. O apply nunca o abre, sobrescreve ou remove — seu arquivo fica byte a byte como estava.

O doctor reporta CRITICAL com diretórios órfãos depois de um apply bem-sucedido.

saída: 0 · 2 com --strict

Significado: O workspace contém diretórios que a especificação não declara. Diretórios intermediários criados para uma entrada aninhada não contam aqui — eles fazem parte da estrutura declarada.
O que verificar: A lista orphan_directories sob doctor --json. Saídas de build e diretórios temporários são a causa usual.
Próximo passo: Declare-os se pertencem à estrutura, ou aceite o relato: nada os remove.

O verify imprime Status: INVALID e sai com 2.

saída: 2

Significado: Um diretório declarado — ou um implicado por uma entrada aninhada — está faltando no workspace. Um arquivo comum parado em um caminho declarado também conta como faltante: um diretório declarado só é satisfeito por um diretório. O verify é uma checagem somente leitura e não alterou nada.
O que verificar: A lista de diretórios faltantes impressa abaixo da linha de status.
Próximo passo: Aplique a estrutura, ou corrija a especificação se o diretório não deveria ser declarado. O código de saída do verify pode ser usado diretamente como portão de pipeline.

O status reporta Lock file: NOT FOUND depois do apply.

saída: 2

Significado: Um apply bem-sucedido registra o lock, tenha ele criado a estrutura, feito-a crescer ou encontrado tudo já conforme. NOT FOUND depois de aplicar significa, portanto, que o apply nunca chegou a esse ponto.
O que verificar: Se a execução foi um --dry-run, ou se o apply foi bloqueado pelo desvio ou falhou. Nenhum desses casos escreve lock.
Próximo passo: Rode o apply sem --dry-run e confirme que ele sai com 0; o lock é escrito na mesma execução.

O policy reporta uma violação, mas o comando ainda assim termina com sucesso.

saída: 0

Significado: O comando policy apenas reporta por padrão: ele imprime a violação e sai com 0, de modo que adicionar um bloco policy não pode quebrar um pipeline que estava verde no dia anterior. O --strict é a opção que transforma o mesmo achado em saída 2.
O que verificar: A lista de violações impressa, que dá cada caminho relativo à raiz da estrutura.
Próximo passo: Aceite o relato, ou passe --strict para usá-lo como portão. doctor --strict, status e verify também saem com 2 diante de um problema estrutural.

UnicodeEncodeError: 'charmap' codec can't encode character

saída: 5

Significado: Um console do Windows usando uma code page legada não consegue renderizar os glifos de status que a CLI imprime.
O que verificar: Se o terminal está rodando em uma codificação diferente de UTF-8.
Próximo passo: Defina PYTHONIOENCODING=utf-8 no ambiente, ou rode o comando em um terminal UTF-8.

Se nada disso corresponder

Confirme primeiro a especificação com orvienm validate .orvienm.yaml, e então inspecione o workspace com orvienm doctor .orvienm.yaml --json, que reporta a raiz, os diretórios faltantes, os diretórios não declarados, a presença do lock e o estado do fingerprint em um único objeto.

A Referência da especificação lista cada chave e regra aceitas, e a Referência da CLI dá o comportamento exato e os códigos de saída de cada comando.