Este documento descreve o fluxo completo para escrever arquivos .val com
tipos e usar o Zed com hover e diagnóstico do Valence.
O modelo (v1.0)
.val é Elixir estrito, não um dialeto:
- o arquivo é Elixir válido (o Mix compila junto com os
.ex); - todo
defpúblico precisa de@spec— sem spec é erro de compilação; - o corpo de cada função com
@specé conferido contra o tipo de retorno declarado (mismatch evidente vira erro de compilação); casenão-exaustivo sobre união tagueada é erro de compilação.
A sintaxe nova com tipos inline (def f(x :: integer) -> integer) fica para a
fase seguinte; hoje o typing é @spec + checagem estrita.
Exemplo (também em examples/operacoes_credito/lib/operacoes_credito/producers/scoring.val):
defmodule MeuApp.Scoring do
@spec classify(integer()) :: :low | :mid | :high
def classify(score) do
cond do
score < 30 -> :low
score < 70 -> :mid
true -> :high
end
end
@spec label(integer()) :: String.t()
def label(score) do
case classify(score) do
:low -> "baixo"
:mid -> "médio"
:high -> "alto"
end
end
endInstalação no projeto Phoenix (Mix)
# mix.exs
defp deps do
[
{:valence, "~> 1.0", runtime: false}
]
end
def project do
[
# ...
compilers: [:valence] ++ Mix.compilers()
]
endmix deps.get
mix compile
# ==> valence
# ==> meu_app
# Valence: 1 arquivo(s) .val compilado(s)
# Generated meu_app app
Erro estrito aparece como erro de compilação normal (e sai 1):
lib/meu_app/scoring.val:5: @spec ausente para sem_spec/1
lib/meu_app/scoring.val:9: @spec de wrong/1 declara String.t(), mas o corpo infere integer()
lib/meu_app/scoring.val:14: case não-exaustivo sobre :a | :b; falta :bO compilador :valence roda antes do compilador Elixir, valida os .val e
grava os .beam no _build. Erros aparecem como erro de compilação normal:
lib/meu_app/scoring.val:3: def sem @spec (modo estrito .val)LiveView/Phoenix em .val
.val é Elixir válido, então uma LiveView é escrita normalmente — macros do
app, HEEx e rotas funcionam:
defmodule MeuAppWeb.ProducersLive do
use MeuAppWeb, :live_view
@impl true
def mount(_params, _session, socket) do
{:ok, assign(socket, :producers, [%{id: 1, name: "Maria"}])}
end
@impl true
def render(assigns) do
~H"""
<ul id="producers">
<li :for={producer <- @producers}>{producer.name}</li>
</ul>
"""
end
endColoque a rota no router como qualquer LiveView:
live "/producers", ProducersLiveDetalhes do compilador:
:valenceroda antes do Elixir e agenda um hook depois do:app; é ali que os.valsão validados/compilados, já com macros e structs do app disponíveis;- o router não gera warning de
Módulo.__live__/0indefinido (os módulos.valentram emno_warn_undefined), entãomix compile --warnings-as-errorspassa; - callbacks com
@impl(mount/render/handle_event) não exigem@spec;defpúblico sem@implcontinua exigindo; - limite: um
.exnão pode depender de um módulo.valem tempo de compilação (struct/macro). Referência por rota/atômico e chamadas em runtime funcionam; se precisar de struct/macro, mantenha aquele módulo em.ex.
Tipos de bibliotecas (Ecto, Phoenix, stdlib)
O LSP roda como escript, fora do Mix. No initialize ele adiciona os
_build/*/lib/*/ebin (e deps/ebin) ao code path, então specs de Ecto,
Phoenix, PubSub, stdlib etc. são lidas do beam — não só o código do projeto.
Exemplos reais:
Repo.insert(cs)
# {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}
Phoenix.PubSub.broadcast(pubsub, topic, msg)
# :ok | {:error, term()}
Ecto.Changeset.cast(data, params, [:name])
# Ecto.Changeset.t()Hover, completion (Ecto., Repo. etc.) e signature help
(textDocument/signatureHelp) usam essas specs; mix valence.type também, já
dentro do Mix. Se você recompilar as deps com o LSP aberto, reinicie o language
server para ele recarregar os ebin.
Inferência de retorno (funções sem @spec)
Como no TypeScript, o LSP infere o tipo de retorno de funções do projeto que
não têm @spec (cacheado; guarda contra recursão):
defmodule Helper do
def greet, do: "oi" # greet() -> String.t()
def double(x), do: x * 2 # double(1) -> integer()
endA inferência usa o mesmo motor das expressões (literais, chamadas com
@spec/deps, aritmética etc.). Limites: corpo que dependa de funções cujas
specs não existem no escript (ex.: Process.get/1) cai em dynamic(); em
mix valence.type a stdlib está disponível e o mesmo corpo vira term().
Para API pública precisa, declare @spec.
Assigns de LiveView
O LSP lê estaticamente assign/2,3 e assign_new/3 nos callbacks
(mount, handle_params, handle_event, handle_info, update) e infere
o tipo de cada valor no contexto do módulo. Dentro de ~H"""...""":
- hover em
@assignmostra o tipo inferido; - completion depois de
@lista os assigns com o tipo e insere o nome.
def mount(_params, _session, socket) do
{:ok, assign(socket, :producers, Producers.list(...))}
end
# no template:
# {@producers} hover -> @producers: [Producer.t()]Assigns e parâmetros de callback vêm do contrato implícito de
use ... :live_view (a macro não aparece como import no source):
assign/2,3,assign_new/3,update/3,push_event/3retornamPhoenix.LiveView.Socket.t()(o beam do Phoenix não traz@specdessas funções; o contrato é declarado pelo Valence);socketemmount/handle_event/handle_params/handle_info/updateé tipado comoPhoenix.LiveView.Socket.t();render(assigns)recebe um mapa com os assigns inferidos (ex.:%{count: 0}).
Limites: assigns condicionais/dinâmicos viram dynamic(); on_mount/hooks
não são analisados; não há diagnóstico de assign desconhecido no template.
Signature help (parâmetros do Ecto e cia.)
Com o cursor dentro dos parênteses (Repo.insert(, Ecto.Changeset.cast(),
o LSP devolve a assinatura com os tipos dos parâmetros e o parâmetro ativo
(contagem de vírgulas). Funciona para funções do projeto, deps e módulos
externos; chamadas aninhadas/multilinha ficam de fora nesta versão.
PubSub: payload tipado no handle_info
O LSP mantém um registro estático dos broadcasts do projeto
(Phoenix.PubSub.broadcast/3/broadcast!/3 com {:evento, payload} ou
{:evento, id, payload}) e tipa a variável correspondente no
handle_info({:evento, payload}, ...); hover no evento do broadcast também
mostra o payload.
# publisher
Phoenix.PubSub.broadcast(MyApp.PubSub, "producers", {:created, %{id: 1}})
# subscriber — hover em payload:
def handle_info({:created, payload}, socket), do: {:noreply, assign(socket, :p, payload)}
# payload: %{id: 1}Limites: evento precisa ser átomo literal; payload é inferido estaticamente; tópicos dinâmicos são ignorados (não há execução de broadcast).
Snippets de callbacks no editor
O LSP do Valence devolve completion de snippet para os callbacks mais
comuns (quando o cliente anuncia snippetSupport, como o Zed):
mount/3, handle_event/3, handle_params/3, handle_info/2,
update/2, handle_async/3, render/1, init/1, handle_call/3,
handle_cast/2, terminate/2.
Digite o prefixo (ex.: mount) e aceite a completion: o editor insere
@impl true
def mount(\${1:_params}, \${2:_session}, \${3:socket}) do
\${0}
endcom tabstops nos parâmetros. Se o cliente não suporta snippets, nada é enviado (só keywords/módulos/funções/campos).
Formatar e corrigir no Zed (Cmd+S / Cmd+.)
O LSP implementa textDocument/formatting (formatter do Elixir via
Code.format_string!/2, respeitando line_length/locals_without_parens
do .formatter.exs) e textDocument/codeAction (quick fixes).
Para o Cmd+S formatar .val, configure o Zed (o padrão do Zed liga
format-on-save só para algumas linguagens, Val não está entre elas):
"languages": {
"Val": {
"formatter": "language_server",
"format_on_save": "on"
}
}O Cmd+. abre as code actions disponíveis:
- Suprimir diagnóstico com
# valence:ignore— insere o comentário na linha do diagnóstico; o checker normal e o modo estrito passam a ignorar aquela linha (inclusive nomix compile/mix valence.check); - Adicionar
@impl trueantes de callback — paradefdemount/3,handle_event/3,handle_info/2,render/1etc. sem@impl.
O formatter ignora import_deps/plugins do .formatter.exs (exigiriam o
Mix carregado); as demais opções são aplicadas.
Reload automático no phx.server
O Phoenix.CodeReloader reexecuta apenas os reloadable_compilers; inclua
:valence no endpoint de dev:
# config/dev.exs
config :meu_app, MeuAppWeb.Endpoint,
# ...
reloadable_compilers: [:phoenix_live_view, :gettext, :elixir, :valence, :app]Com isso, salvar um .val e recarregar a página recompila o arquivo no
servidor rodando (sem reiniciar): o :valence detecta que o app já está no ar,
compila na hora e grava o .beam. A detecção é por digest (manifest em
_build/<env>/lib/<app>/.valence_manifest), então edições no mesmo segundo e
restaurações de backup também contam, sem warning de "redefining module".
Comandos
mix valence.check "lib/**/*.ex" "lib/**/*.val"
mix valence.type lib/meu_app/scoring.val:8:5
mix valence.type lib/meu_app/scoring.val:8:5 --beam-path "../projeto/_build/dev/lib/*/ebin"
O check também roda o modo estrito nos .val (spec obrigatória,
corpo-vs-spec, exaustividade como diagnóstico). O type responde em .val
como responde em .ex (mesmo AST).
Zed
1. Deixe o servidor LSP disponível
O jeito mais robusto é um escript global:
cd caminho/para/valence
mix deps.get
mix escript.build
install -m 755 valence ~/.local/bin/valence # ~/.local/bin já está no PATH
valence --version # Valence 1.0.0
Nesta máquina o escript já está instalado em ~/.local/bin/valence.
Alternativa: a extensão também sabe iniciar mix valence.lsp se mix estiver
no PATH (precisa do Valence como dep do projeto).
2. Instale a extensão de dev
- No Zed:
Cmd+Shift+P→ zed: install dev extension - Selecione a pasta
zed-valence/(dentro do repo do Valence, já com o wasm buildado emtarget/wasm32-wasip2/release/zed_valence.wasm) - Espere a compilação da gramática tree-sitter-elixir (primeira vez baixa o repositório; Zed cuida do wasi-sdk)
- Abra o projeto e crie/abra um arquivo
.val - Se a extensão já estava instalada antes de mudar snippets/queries, rode
zed: rebuild dev extension(ou reinstale a dev extension) e reinicie o Zed para carregarsnippets/config.tomlnovos
A extensão registra a linguagem Val (sufixo .val, highlighting do Elixir)
e inicia o servidor Valence nela.
3. O que você vê
- syntax highlighting completo: as queries do tree-sitter-elixir estão em
languages/val/(highlights, brackets, indents, injections, outline, overrides, textobjects), no rev pinado da gramática; - snippets (
snippets/val.json, registrados noextension.toml):def,defp,defmodule,defstruct,spec,type,moduledoc,case,cond,with,for,ifelse,|>,test,describe,setup,setup_all,genserver,schema,inspect; - IntelliSense: hover com tipo renderizado (
String.t(),%OperacoesCredito.Producers.Producer{...},dynamic()), diagnósticos no editor (prompt de@spec, corpo-vs-spec,casenão-exaustivo, erro de sintaxe) e completion (palavras-chave, módulos, funções com assinatura, campos de struct, variáveis locais); - ícone: tema "Valence Icons" (
icon_themes/valence.json+icons/dark/icons/light), baseado no Colored Zed Icons Theme (TheRedXD / Zed Industries): ícones coloridos dark/light +.val→ "V" do Valence. Ative uma vez:Cmd+Shift+P→ icon theme selector: toggle → Valence Icons.
Troubleshooting
| sintoma | causa/solução |
|---|---|
| extensão não inicia o LSP | instale o escript e confira valence --version; ou garanta mix no PATH do Zed (abra o Zed pelo terminal para herdar o PATH) |
| nenhum diagnóstico/hover | o LSP precisa do projeto aberto na raiz (tem mix.exs); veja zed: open log |
.val sem highlighting | a extensão de dev não foi instalada ou o grammar ainda está compilando (primeira vez baixa o tree-sitter) |
| erros de dependência no LSP | mix deps.compile no projeto (o Valence lê .beam de deps e nunca compila sozinho) |
Limites atuais
- Sem sintaxe inline de tipos (fase 4);
@specé a superfície. - Checagem corpo-vs-spec é conservadora:
dynamic()nunca acusa mismatch. - Sem checagem de exaustividade para
cond/if(sócasee handlers de GenServer tipado). .vale.exconvivem no mesmo projeto; o compilador:valencesó olha.val.
Próximo passo (fase 4)
Sintaxe inline que desugar para @spec (def f(x :: integer) -> integer) com
source map para o LSP; depois ADTs/newtypes e exaustividade como erro em toda
a linguagem.
Validado nesta máquina (v1.0)
mix compilede um projeto demo com.val:Valence: 1 arquivo(s) .val compilado(s)e módulo executável (mix run -e 'IO.inspect(ValDemo.Greeter.describe(0))'→"baixo").- Erro estrito em
.val(sem @spec, corpo incompatível,casenão-exaustivo):mix compilesai 1 com as 3 linhasarquivo:linha: mensagem. mix valence.check "lib/**/*.ex" "lib/**/*.val"→ 0 diagnósticos no projeto demo.mix valence.type lib/demo/greeter.val:17:10→:low | :high.- LSP ponta a ponta (escript
valence lsp): initialize comhoverProvider=true,didOpende.valpublica diagnósticos (inclusive os do modo estrito), hover devolve:low | :mid | :high, shutdown funciona. - LiveView em
.val: rota Phoenix renderizou HTTP 200 com conteúdo (mount+ HEEx), build limpo com--warnings-as-errors, incremental sem recompilar e erro estrito (@spec ausente) derrubando o build comarquivo.val:linha. - Reload em
.val: comreloadable_compilersincluindo:valence, alterar e restaurar o arquivo refletiu na página sem reiniciar o servidor (inclusive no mesmo segundo), sem warning de módulo redefinido. - Snippets de callback: completion real do escript devolveu
mountcominsertTextFormat: 2e@impl true+def mount(...). - Formatar/corrigir: escript devolveu edição de formatação (
.valcru → indentado) e code actions# valence:ignorea partir dos diagnósticos reais;Stricthonra o comentário também no build. - Zed: settings com
languages.Val.formatter = language_servereformat_on_save = on(Cmd+S),cmd-.= ToggleCodeActions (Cmd+.). - Deps tipadas: LSP carregou
_builde devolveuRepo.insert -> {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()},PubSub.broadcast -> :ok | {:error, term()}e assinatura deEcto.Changeset.cast. - Assigns: hover em
@producersno HEEx devolveu o tipo inferido e completion de@listou o assign (textEdit@count). - PubSub: hover em
payloaddehandle_info({:created, payload}, ...)devolveu%{id: 1, name: String.t()}a partir do broadcast do projeto. - Inferência:
def greet, do: "oi"+greet()devolveuString.t(); recursão devolvedynamic()sem entrar em loop; nofoo_live.val,socket/assign/updatederamPhoenix.LiveView.Socket.t(). - LiveView implícito: no
foo_live.valdo projeto real, hover emassign(...),update(...)e nosocketdo corpo devolveuPhoenix.LiveView.Socket.t();@countdevolveu0eRepo.insertdevolveu{:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}.