Pular para o conteúdo principal
Versão: 0.4.0

Validando Módulos

Valide seus módulos para garantir que estão estruturados corretamente e prontos para distribuição.

Validando um Módulo​

invowk validate ./mytools.invowkmod

Saída para um módulo válido com um invowkfile:

Module Validation
• Path: /home/user/mytools.invowkmod
• Name: mytools

✓ Module is valid

✓ Structure check passed
✓ Naming convention check passed
✓ Required files present
✓ Invowkfile parses successfully

invowk validate sempre executa validação completa, incluindo parsing de invowkfile e verificações da árvore de comandos quando o módulo contém um invowkfile.cue.

O que é Validado​

Checagens de Estrutura​

  • Diretório do módulo existe
  • invowkmod.cue obrigatório na raiz
  • invowkfile.cue é opcional (módulos apenas de biblioteca são permitidos)
  • Sem módulos aninhados (exceto dentro de invowk_modules/)

Checagens de Segurança​

  • Sem symlinks: Symlinks não são permitidos em módulos por motivos de segurança. Eles podem escapar do diretório do módulo durante extração (vulnerabilidade zip-slip).

Checagens de Compatibilidade​

  • Nomes reservados no Windows: Arquivos chamados CON, PRN, AUX, NUL, COM1-COM9 ou LPT1-LPT9 geram um aviso de compatibilidade. Esses nomes são reservados no Windows e podem causar problemas ao extrair módulos em sistemas Windows.

Checagens de Nomenclatura​

  • Nome da pasta termina com .invowkmod
  • Prefixo do nome segue as regras (começa com letra, alfanumérico + pontos)
  • ID do módulo em invowkmod.cue corresponde ao prefixo do nome da pasta
  • Sem caracteres inválidos (hífens, underscores)

Checagens de Invowkfile​

Quando o módulo contém um invowkfile.cue, estas são sempre verificadas:

  • Invowkfile faz parse sem erros
  • Sintaxe CUE é válida
  • Restrições do schema são atendidas
  • Estrutura da árvore de comandos é válida (sem conflitos args + subcomandos)

Erros de Validação​

Invowkmod Ausente​

Module Validation
• Path: /home/user/bad.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [structure] missing required invowkmod.cue

Nome Inválido​

Module Validation
• Path: /home/user/my-tools.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [naming] module name 'my-tools' contains invalid characters (hyphens not allowed)

Módulo Aninhado​

Module Validation
• Path: /home/user/parent.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [structure] nested.invowkmod: nested modules are not allowed (except in invowk_modules/)

Invowkfile Inválido​

Module Validation
• Path: /home/user/broken.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [invowkfile] parse error at line 15: expected '}', found EOF

Validação em Lote​

Valide múltiplos módulos:

# Validate all modules in a directory
for mod in ./modules/*.invowkmod; do
    invowk validate "$mod"
done

Integração com CI​

Adicione validação de módulos no seu pipeline de CI:

# GitHub Actions example
- name: Validate modules
  run: |
    for mod in modules/*.invowkmod; do
      invowk validate "$mod"
    done

Problemas Comuns​

Separadores de Caminho Errados​

// Bad - Windows-style
script: "scriptsuild.sh"

// Good - Forward slashes
script: "scripts/build.sh"

Escapando o Diretório do Módulo​

// Bad - tries to access parent
script: "../outside/script.sh"

// Good - stays within module
script: "scripts/script.sh"

Caminhos Absolutos​

// Bad - absolute path
script: "/usr/local/bin/script.sh"

// Good - relative path
script: "scripts/script.sh"

Melhores Práticas​

  1. Valide antes de commitar: Detecte problemas cedo
  2. Valide no CI: Impede módulos quebrados de sair
  3. Corrija problemas imediatamente: Não deixe dívida de validação acumular

Próximos Passos​