Fluxograma de Precedência de Descoberta

Este diagrama mostra como comandos são descobertos e como conflitos são resolvidos quando o mesmo nome de comando aparece em múltiplos locais.

Fluxo de Descoberta

Resolução de Conflitos

Quando o mesmo nome de comando existe em múltiplos locais:

Regras de Resolução

Prioridade	Fonte	Caminho de Exemplo
1 (maior)	invowkfile do diretório atual	./invowkfile.cue
2	Módulos locais	./mytools.invowkmod/
3	Includes configurados	/opt/invowk-modules/tools.invowkmod
4 (menor)	Diretório de comandos do usuário	~/.invowk/cmds/mytools.invowkmod/

Princípios chave:

• Mais perto do diretório de trabalho = maior prioridade.
• Includes configurados têm precedência sobre o diretório de comandos do usuário porque representam configuração explícita e intencional.
• O diretório de comandos do usuário (~/.invowk/cmds/) descobre apenas diretórios *.invowkmod como filhos imediatos (não recursivo). Invowkfiles avulsos não são descobertos a partir desse local.

Detalhes da Descoberta de Módulos

Campos Obrigatórios do Módulo

// invowkmod.cue
module: "com.example.mymodule"  // Convenção de nomenclatura RDNS
version: "1.0.0"                // Versão semântica

// Opcional
description: "My useful module"
requires: [
    {
        git: "https://github.com/org/repo.git"
        version: "v1.0.0"
    }
]

Resolução de Dependências

Visibilidade de Dependências Transitivas

De	Pode Acessar	Não Pode Acessar
Módulo A	comandos de A, comandos de B	comandos de C (transitivo)
Módulo B	comandos de B, comandos de C	-
invowkfile Raiz	Próprios comandos, deps diretas	Deps transitivas

Por que esta restrição?

• Previne acoplamento implícito a dependências transitivas
• Torna dependências explícitas em cada módulo
• Permite upgrades de dependências sem quebrar consumidores

Configuração de Includes

Invowkfiles e módulos adicionais são configurados em ~/.config/invowk/config.cue:

includes: [
    {path: "/opt/company-invowk-modules/tools.invowkmod"},
    {path: "/home/shared/invowk/invowkfile.cue"},
]

Ordem de Processamento de Entradas

Cache de Descoberta

Problemas Comuns de Descoberta

Problema: Comando Não Encontrado

Problema: Versão Errada do Comando

Comandos de Debug

# Listar todos os comandos descobertos com fontes
invowk cmd --ivk-verbose

# Validar estrutura do módulo
invowk module validate ./mymodule.invowkmod

Diagramas Relacionados

• Sequência de Execução de Comando - O que acontece após a descoberta
• Fluxograma de Seleção de Runtime - Como runtimes são escolhidos
• Diagrama C4 de Container - Contexto do componente de descoberta