Produto / Linguagem
Uma especificação declarativa para estrutura
Você descreve a estrutura que um sistema deve ter como uma declaração, e não como um script. É isso que torna o mesmo arquivo verificável antes da execução, comparável com um workspace e conferível depois.
Modelo declarativo
Uma especificação declara qual a estrutura deve ser, não os passos para construí-la. Não há ordem a acertar nem script a reexecutar com cuidado, porque a descrição não é uma sequência de ações.
É isso que torna o mesmo arquivo utilizável em todas as etapas: ele pode ser verificado antes de qualquer execução, comparado com um workspace para produzir um plano e comparado de novo depois para conferir o resultado.
Conceitos centrais
- Nome
- structure.name declara o diretório que a especificação governa. Ele é resolvido em relação a onde o comando roda, e é a raiz de tudo o que o engine cria.
- Diretórios
- structure.directories é uma lista plana de entradas de diretório sob essa raiz. Cada entrada é um nó — a unidade sobre a qual a validação, o planejamento e a verificação operam.
- Version e style
- version declara o formato contra o qual o arquivo foi escrito. style é opcional e aceita enterprise, technical ou hybrid; ambos participam do fingerprint da especificação.
- Uma superfície fechada
- O Alpha atual aceita quatro chaves de raiz — version, structure, style e policy — e rejeita qualquer outra. O formato é deliberadamente pequeno e só cresce quando o engine implementa mais.
Uma especificação
A menor especificação útil é uma version e uma structure.
structure.yaml
version: 1
structure:
name: project
directories:
- src
- data
- docsEsta página explica o modelo, em vez de enumerar o formato. Cada chave aceita, seus valores permitidos e as regras aplicadas às entradas de diretório estão listados na Referência da especificação.
Especificação e estrutura
A especificação e a hierarquia de diretórios são duas representações de uma mesma coisa. A especificação é o contrato; a hierarquia é o estado que esse contrato governa.
Estrutura em disco
- platform/
- core/
- data/
- docs/
structure.yaml
version: 1
structure:
name: platform
directories:
- core
- data
- docsPor que a validação é possível
Como a especificação é uma descrição e não um programa, ela pode ser examinada antes de ser usada. Estrutura malformada, definições ilegíveis e problemas estruturais são encontrados lendo a especificação, não executando-a e observando o que quebra.
Por isso a validação acontece antes do planejamento, e o planejamento antes que qualquer coisa chegue ao sistema de arquivos.