Pular para o conteúdo principal
Versão: 0.1.0-alpha.3

Validando Módulos

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

Validação Básica​

invowk module validate ./mytools.invkmod

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

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

✓ Module is valid

✓ Structure check passed
✓ Naming convention check passed
✓ Required files present

Validação Profunda​

Adicione --deep para também fazer parse e validar o invkfile (quando presente):

invowk module validate ./mytools.invkmod --deep

Saída:

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

✓ Module is valid

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

O que é Validado​

Checagens de Estrutura​

  • Diretório do módulo existe
  • invkmod.cue obrigatório na raiz
  • invkfile.cue é opcional (módulos apenas de biblioteca são permitidos)
  • Sem módulos aninhados (exceto dentro de invk_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 .invkmod
  • Prefixo do nome segue as regras (começa com letra, alfanumérico + pontos)
  • ID do módulo em invkmod.cue corresponde ao prefixo do nome da pasta
  • Sem caracteres inválidos (hífens, underscores)

Checagens Profundas (com --deep)​

  • Invkfile faz parse sem erros (se presente)
  • Sintaxe CUE é válida
  • Restrições do schema são atendidas

Erros de Validação​

Invkmod Ausente​

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

✗ Module validation failed with 1 issue(s)

  1. [structure] missing required invkmod.cue

Nome Inválido​

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

✗ 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.invkmod

✗ Module validation failed with 1 issue(s)

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

Invkfile Inválido (deep)​

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

✗ Module validation failed with 1 issue(s)

  1. [invkfile] 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/*.invkmod; do
    invowk module validate "$mod" --deep
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/*.invkmod; do
      invowk module validate "$mod" --deep
    done

Problemas Comuns​

Separadores de Caminho Errados​

// Bad - Windows-style
script: "scripts\\build.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. Use --deep: Captura erros de invkfile
  3. Valide no CI: Impede módulos quebrados de sair
  4. Corrija problemas imediatamente: Não deixe dívida de validação acumular

Próximos Passos​