Fluxograma de Precedência de Descoberta

Este diagrama mostra como comandos são descobertos e como colisões de nomes de comando são tratadas entre fontes.

Fluxo de Descoberta

Resolução de Conflitos

Quando nomes colidem, o Invowk trata dois casos diferentes:

Regras de Resolução

Caso	Comportamento
Mesmo nome completo de comando descoberto em múltiplas fontes	A primeira fonte descoberta vence (ordem de precedência)
Mesmo nome simples de comando em fontes diferentes	Marca como ambíguo; o usuário deve desambiguar (@source / --ivk-from)

Ordem de precedência de descoberta:

1. invowkfile do diretório atual (./invowkfile.cue)
2. Módulos locais (./*.invowkmod)
3. Includes configurados (caminhos de módulo em config.Includes)
4. Diretório de comandos do usuário (~/.invowk/cmds/*.invowkmod, somente módulos, não recursivo)

Módulos vendorizados (invowk_modules/) são escaneados um nível abaixo de cada fonte de módulo descoberta.

Detalhes da Descoberta de Módulos

Campos Obrigatórios do Módulo

// invowkmod.cue
module: "com.example.mymodule"  // RDNS naming convention
version: "1.0.0"                // Semantic version

// Optional
description: "My useful module"
requires: [
    {
        git_url: "https://github.com/org/repo.git"
        version: "^1.0.0"
    }
]

Resolução de Dependências

Visibilidade de Dependências Transitivas

Esta checagem de visibilidade se aplica a dependências declaradas em depends_on.cmds durante validação estática. Ela não intercepta subprocessos arbitrários chamados em runtime.

De	Pode Acessar	Não Pode Acessar
Módulo A	comandos de A, módulos globais instalados, comandos de B	comandos de C (transitivo)
Módulo B	comandos de B, módulos globais instalados, comandos de C	-
invowkfile raiz	Comandos descobertos	Restrições de escopo não se aplicam; falhas são de descoberta ou resolução explícita de dependências

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

Módulos adicionais são configurados no arquivo global de config resolvido:

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

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 descoberta do workspace (reporta todos os diagnósticos)
invowk validate

# Validar um módulo específico
invowk 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