O arquivo-índice

O que é o arquivo-índice

O arquivo <projeto>.spell é o ponto de entrada de um projeto SPELL. Ele não contém lógica de negócio própria — sua função é declarar o nome e versão do projeto e listar os arquivos de módulo que compõem a especificação. O spellcomp lê o arquivo-índice primeiro e, a partir dele, carrega os demais arquivos.

É análogo ao arquivo .dpr do Delphi em relação aos arquivos .pas: ele não contém código, apenas declara a estrutura do projeto.

Convenção de nomenclatura

O arquivo-índice segue a convenção de ter o mesmo nome do diretório do projeto:

agendamedica/
└── agendamedica.spell   ← arquivo-índice

O spellcomp compile . descobre o arquivo-índice por essa convenção. Se o arquiteto preferir um nome diferente, passa o arquivo explicitamente:

spellcomp compile minha-spec.spell

Estrutura do arquivo-índice

Um arquivo-índice completo tem o bloco Projeto e o bloco Arquivos:

agendamedica.spell

Projeto {
  nome: AgendaMedica
  versao: 1.0
  descricao: Sistema de agendamento de consultas médicas
  padroes: padroes.spell
}

Arquivos {
  - modulo-usuarios.spell
  - modulo-medicos.spell
  - modulo-consultas.spell
  - modulo-notificacoes.spell
}

Bloco Projeto — campos

Campo	Obrigatório	Descrição
`nome`	Sim	Nome do projeto. Usado como prefixo nos arquivos gerados. Sem espaços.
`versao`	Sim	Versão da spec. String livre.
`descricao`	Não	Descrição curta do sistema. Aparece no cabeçalho dos arquivos gerados.
`padroes`	Não	Caminho para o arquivo de Padrões de Engenharia. Padrão: `padroes.spell`.

Bloco singleton O bloco Projeto é singleton — pode existir apenas uma vez em todo o projeto. Declarado em mais de um arquivo, o compilador emite ❌ ERRO e interrompe.

Campo padroes

O campo padroes declara qual arquivo contém os Padrões de Engenharia. Se omitido, o compilador assume padroes.spell por convenção. O arquivo declarado é carregado antes de qualquer módulo e não deve aparecer no bloco Arquivos.

O campo aceita caminho relativo — útil para compartilhar padrões corporativos entre projetos:

// Padrões corporativos compartilhados entre projetos
Projeto {
  nome: MeuSistema
  versao: 1.0
  padroes: ../padroes-corporativos/padroes-empresa.spell
}

Regras do compilador para o campo padroes:

Campo padroes duplicado no mesmo Projeto { } → ❌ ERRO: campo duplicado
Se omitido e padroes.spell não existir → o compilador prossegue sem Padrões de Engenharia e emite ℹ️ INFO
O arquivo declarado não deve aparecer no bloco Arquivos { }

Bloco Arquivos

O bloco Arquivos lista os módulos do projeto na ordem em que devem ser carregados. Cada linha é um caminho de arquivo relativo ao diretório do arquivo-índice:

Arquivos {
  - fase-1/usuarios.spell
  - fase-1/autenticacao.spell
  - fase-2/pedidos.spell
  - fase-2/pagamentos.spell
  - integracao-fiscal.spell
}

A ordem importa: é a ordem em que o compilador carrega os módulos para construir o AST. O arquivo de padroes é sempre carregado primeiro, independentemente de onde declarado.

Projetos simples sem bloco Arquivos

O bloco Arquivos é opcional. Em projetos simples — com poucos módulos ou spec concentrada em um único arquivo — o arquiteto pode colocar tudo no arquivo-índice e o spellcomp o trata como a spec completa do projeto:

spec-simples.spell — tudo em um arquivo

Projeto {
  nome: LandingPage
  versao: 1.0
  descricao: Formulário de captura de leads com envio de e-mail
}

Dados {
  table Lead {
    nome: texto(100), obrigatorio
    email: texto(200), unico, obrigatorio
    empresa: texto(100), opcional
    capturado_em: data-hora, obrigatorio
  }
}

Endpoints {
  endpoint CadastrarLead {
    rota: POST /leads
    autenticacao: nao-requerida

    Entrada {
      nome: texto(100), obrigatorio
      email: texto(200), obrigatorio
      empresa: texto(100), opcional
    }

    Respostas {
      201: Lead cadastrado — enviar e-mail de boas-vindas
      409: E-mail já cadastrado
    }
  }
}