Valence como linguagem: .val + Zed

Copy Markdown View Source

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 def pú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);
  • case nã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
end

Instalação no projeto Phoenix (Mix)

# mix.exs
defp deps do
  [
    {:valence, "~> 1.0", runtime: false}
  ]
end

def project do
  [
    # ...
    compilers: [:valence] ++ Mix.compilers()
  ]
end
mix 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 :b

O 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
end

Coloque a rota no router como qualquer LiveView:

live "/producers", ProducersLive

Detalhes do compilador:

  • :valence roda antes do Elixir e agenda um hook depois do :app; é ali que os .val são validados/compilados, já com macros e structs do app disponíveis;
  • o router não gera warning de Módulo.__live__/0 indefinido (os módulos .val entram em no_warn_undefined), então mix compile --warnings-as-errors passa;
  • callbacks com @impl (mount/render/handle_event) não exigem @spec; def público sem @impl continua exigindo;
  • limite: um .ex não pode depender de um módulo .val em 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()
end

A 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 @assign mostra 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/3 retornam Phoenix.LiveView.Socket.t() (o beam do Phoenix não traz @spec dessas funções; o contrato é declarado pelo Valence);
  • socket em mount/handle_event/handle_params/handle_info/update é tipado como Phoenix.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}
end

com 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 no mix compile/mix valence.check);
  • Adicionar @impl true antes de callback — para def de mount/3, handle_event/3, handle_info/2, render/1 etc. 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

  1. No Zed: Cmd+Shift+P → zed: install dev extension
  2. Selecione a pasta zed-valence/ (dentro do repo do Valence, já com o wasm buildado em target/wasm32-wasip2/release/zed_valence.wasm)
  3. Espere a compilação da gramática tree-sitter-elixir (primeira vez baixa o repositório; Zed cuida do wasi-sdk)
  4. Abra o projeto e crie/abra um arquivo .val
  5. 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 carregar snippets/config.toml novos

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 no extension.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, case nã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

sintomacausa/solução
extensão não inicia o LSPinstale 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/hovero LSP precisa do projeto aberto na raiz (tem mix.exs); veja zed: open log
.val sem highlightinga 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 LSPmix 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ó case e handlers de GenServer tipado).
  • .val e .ex convivem no mesmo projeto; o compilador :valence só 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 compile de 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, case não-exaustivo): mix compile sai 1 com as 3 linhas arquivo: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 com hoverProvider=true, didOpen de .val publica 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 com arquivo.val:linha.
  • Reload em .val: com reloadable_compilers incluindo :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 mount com insertTextFormat: 2 e @impl true + def mount(...).
  • Formatar/corrigir: escript devolveu edição de formatação (.val cru → indentado) e code actions # valence:ignore a partir dos diagnósticos reais; Strict honra o comentário também no build.
  • Zed: settings com languages.Val.formatter = language_server e format_on_save = on (Cmd+S), cmd-. = ToggleCodeActions (Cmd+.).
  • Deps tipadas: LSP carregou _build e devolveu Repo.insert -> {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}, PubSub.broadcast -> :ok | {:error, term()} e assinatura de Ecto.Changeset.cast.
  • Assigns: hover em @producers no HEEx devolveu o tipo inferido e completion de @ listou o assign (textEdit @count).
  • PubSub: hover em payload de handle_info({:created, payload}, ...) devolveu %{id: 1, name: String.t()} a partir do broadcast do projeto.
  • Inferência: def greet, do: "oi" + greet() devolveu String.t(); recursão devolve dynamic() sem entrar em loop; no foo_live.val, socket/assign/update deram Phoenix.LiveView.Socket.t().
  • LiveView implícito: no foo_live.val do projeto real, hover em assign(...), update(...) e no socket do corpo devolveu Phoenix.LiveView.Socket.t(); @count devolveu 0 e Repo.insert devolveu {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}.