Referência de Schema do Invowkmod

:::warning Alpha — Schema Pode Mudar O schema do invowkmod ainda está evoluindo. Campos, tipos e regras de validação podem mudar entre releases enquanto estabilizamos o formato. Sempre verifique o changelog ao fazer upgrade. :::

Referência completa para invowkmod.cue, o arquivo de metadados do módulo. Metadados são validados como struct fechado, então campos desconhecidos geram erro de validação.

Estrutura Raiz

Todo módulo deve incluir um arquivo invowkmod.cue com esta estrutura:

#Invowkmod: {
    module:       string               // Required - module identifier
    version:      string               // Required - semver version (e.g., "1.0.0")
    description?: string               // Optional - module description
    author?:      string               // Optional - author or maintainer
    license?:     string               // Optional - SPDX license identifier
    repository?:  string               // Optional - canonical source URL
    requires?:    [...#ModuleRequirement] // Optional - dependencies
}

module

Tipo: string (padrão: ^[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)*$) Obrigatório: Sim

O identificador do módulo. Diretórios de módulos instalados localmente usam este valor como <module-id>.invowkmod. Para subpaths explícitos de dependências, o basename do diretório selecionado deve corresponder a este prefixo antes de .invowkmod. Para uma origem na raiz de um repositório Git, o basename do repositório não precisa corresponder.

module: "mytools"
module: "com.company.devtools"
module: "io.github.username.cli"

version

Tipo: string (padrão: ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$) Obrigatório: Sim

Versão do módulo em formato semver (ex: "1.0.0", "2.1.0-beta.1").

description

Tipo: string Obrigatório: Não

Um resumo curto do propósito do módulo.

author

Tipo: string Obrigatório: Não

Autor ou mantenedor do módulo (texto livre, tipicamente "Nome <email>" ou nome da organização).

license

Tipo: string Obrigatório: Não

Licença do módulo usando um identificador SPDX (ex: "MIT", "Apache-2.0", "MPL-2.0").

repository

Tipo: string (padrão: ^(https://|git@|ssh://)) Obrigatório: Não

URL canônica de origem deste módulo. Apenas esquemas https://, git@ e ssh:// são aceitos.

requires

Tipo: [...#ModuleRequirement] Obrigatório: Não

Lista de dependências de módulos em repositórios Git.

requires: [
    {
        git_url: "https://github.com/example/common.git"
        version: "^1.0.0"
        alias: "common"
    },
]

---

ModuleRequirement

Define uma entrada de dependência:

#ModuleRequirement: {
    git_url: string
    version: string
    alias?:  string
    path?:   string  // Relative subdirectory; traversal is rejected after decode
}

git_url

Tipo: string Obrigatório: Sim

URL do repositório Git. Formas aceitas: HTTPS (https://...), SSH shorthand (git@...) ou URI SSH (ssh://...). O basename do repositório não precisa terminar em .invowkmod.

Quando path é omitido, a raiz do repositório buscado deve conter invowkmod.cue e invowkfile.cue. Módulos filhos não são selecionados automaticamente; declare path em monorepos.

version

Tipo: string Obrigatório: Sim

Restrição de versão semântica usada para resolver uma tag Git. Os formatos aceitos são uma versão semântica simples ou um operador entre ^, ~, >, >=, <, <= ou = seguido por uma versão semântica. O valor da restrição não pode usar prefixo v, lixo no final ou ranges compostos como >=1.0.0 <2.0.0.

alias

Tipo: string Obrigatório: Não

Sobrescreve o ID de origem de comando padrão para esta dependência. Aliases usam regras de command source ID: devem começar com uma letra e podem conter letras, dígitos, ., _ ou -.

path

Tipo: string Obrigatório: Não

Subdiretório dentro do repositório que contém o módulo. Deve ser relativo e apontar diretamente para um diretório cujo basename termina em .invowkmod. O prefixo do basename deve corresponder ao valor module do módulo selecionado. Nomes comuns de segmento com pontos consecutivos são permitidos, mas segmentos de diretório pai como .., caminhos absolutos, caminhos com drive e caminhos UNC/enraizados são rejeitados depois que o Invowk normaliza os separadores.

Limites de Comprimento de Strings

Os limites de strings são medidos em pontos de código Unicode (runes):

Campo	Máximo de runes
module	256
version raiz	64
description	10.240
author	256
license	128
repository	2.048
git_url da dependência	2.048
version da dependência	64
alias da dependência	256
path da dependência	4.096