Lock File de Dependências de Módulos

O lock file (invowkmod.lock.cue) registra as versões exatas de todas as dependências de módulo resolvidas, garantindo builds reprodutíveis ao longo do tempo e entre máquinas.

Ele é gerado automaticamente por invowk module sync e invowk module update.

Exemplo de Lock File

version: "2.0"
generated: "2025-01-10T12:34:56Z"

modules: {
    "https://github.com/example/common.git": {
        git_url:          "https://github.com/example/common.git"
        version:          "^1.0.0"
        resolved_version: "1.2.3"
        git_commit:       "abc123def456789012345678901234567890abcd"
        alias:            "common"
        module_id:        "io.example.common"
        namespace:        "common"
        command_source_id: "common"
        content_hash:     "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
}

Campos da Raiz

Campo	Descrição
version	Versão do formato do lock file (atual: "2.0")
generated	Timestamp de criação do lock file
modules	Mapa de chaves de módulo para entradas travadas

Campos de Entrada de Módulo

Cada entrada em modules contém:

Campo	Descrição
git_url	URL do repositório Git
version	Restrição de versão original de invowkmod.cue
resolved_version	Versão resolvida exata
git_commit	SHA do commit da versão resolvida (reverificado sempre que a mesma versão é resolvida de novo)
alias	Alias de namespace (se definido)
path	Caminho de subdiretório (se definido)
module_id	Identidade canônica do módulo lida de invowkmod.cue
namespace	Namespace de exibição calculado para compatibilidade
command_source_id	ID de origem usado ao publicar comandos para execução/desambiguação
content_hash	Hash SHA-256 do conteúdo da árvore do módulo (reverificado sempre que a mesma versão é resolvida de novo, esteja o módulo em cache ou não)

Chaves de Módulo

A chave no mapa modules é derivada da URL Git e do caminho opcional:

modules: {
    "https://github.com/example/monorepo.git#modules/io.example.cli.invowkmod": {
        git_url: "https://github.com/example/monorepo.git"
        path:    "modules/io.example.cli.invowkmod"
    }
}

Chaves de lock preservam a identidade da declaração de origem. O module_id lido é armazenado separadamente e é usado para nomes canônicos de diretórios locais de cache e vendor, como invowk_modules/io.example.common.invowkmod. Chaves de origem diferentes que resolvem para o mesmo module_id são rejeitadas como colisões canônicas de módulo em vez de sobrescreverem umas às outras.

Notas de Uso

• Commite invowkmod.lock.cue no controle de versão para builds reprodutíveis.
• invowk module add grava o lock file automaticamente (não é necessário executar invowk module sync depois).

Verificações de Integridade Durante o Sync

Quando invowk module sync, add, update ou tidy resolve um módulo para a mesma resolved_version que o lock file já registra, o Invowk verifica se o remoto reproduz a entrada travada:

• O commit obtido precisa ser igual a git_commit. Um commit diferente significa que a tag upstream foi re-apontada, e o sync falha com uma divergência de commit travado.
• O conteúdo do módulo precisa ter o hash content_hash. Isso vale numa máquina nova ou num runner de CI com o cache de módulos vazio, e também para módulos já em cache. Uma cópia nova que falha na verificação é removida do cache.

Nos dois casos, o lock file não é reescrito.

Quando um módulo resolve para uma versão diferente, porque você mudou a restrição ou porque invowk module update encontrou uma versão mais nova, o commit e o hash da entrada antiga não são aplicados. Os valores da nova versão viram a próxima linha de base. Um módulo ainda sem entrada no lock é registrado no primeiro sync, com um aviso de que não tem linha de base de integridade.

Um lock file v1.0 não registra hashes de conteúdo, então suas entradas não detectam adulteração. A descoberta e o invowk module vendor rejeitam módulos vendorizados apoiados nessas entradas, e o sync busca uma cópia nova em vez de confiar no cache. Rode invowk module sync uma vez para atualizar o lock file para v2.0.

Se um re-tag ou uma mudança de conteúdo upstream for intencional, rode invowk module remove <git-url> e depois invowk module add para adicionar o módulo de novo. Isso grava uma nova linha de base sem editar à mão o lock file gerado. Se você suspeitar que o cache local foi modificado, apague o diretório de cache do módulo indicado no erro.

Workflows Comuns

# Resolve and lock
invowk module sync

# Commit the lock file
git add invowkmod.lock.cue
git commit -m "Lock module dependencies"