Tipagem estática incremental para Elixir, arquivos .val e um LSP.

O Valence é uma camada de tipos que convive com o ecossistema: você escreve Elixir normal (ou .val, Elixir estrito) e o servidor responde "qual o tipo desta expressão nesta posição", acusa case/handlers não-exaustivos, tipa assigns de LiveView, payloads de PubSub e as funções de Ecto/Phoenix lidas do beam das deps.

Não é uma linguagem nova: .val é Elixir válido com um contrato mais rígido, compilado pelo Mix.

Instalação

No mix.exs do seu projeto:

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

def project do
  [
    # Phoenix:
    compilers: [:valence, :phoenix_live_view] ++ Mix.compilers(),
    # Sem Phoenix:
    # compilers: [:valence] ++ Mix.compilers(),
    deps: deps()
  ]
end
mix deps.get
mix compile

Requer Elixir 1.20+ (OTP 27+).

.val em 30 segundos

Crie lib/minha_app/scoring.val:

defmodule MinhaApp.Scoring do
  @spec classificar(non_neg_integer()) :: :low | :mid | :high
  def classificar(score) when score < 50, do: :low
  def classificar(score) when score < 100, do: :mid
  def classificar(_score), do: :high
end

O compilador exige @spec em def público, confere corpo contra o retorno e trata caso não-exaustivo como erro de compilação. callbacks com @impl não exigem @spec.

mix compile
mix valence.check "lib/**/*.ex" "lib/**/*.val"
mix valence.type lib/minha_app/scoring.val:2:5

Editor

Zed

O LSP é iniciado pela extensão com mix valence.lsp: basta o projeto ter a dependência do Valence. Instale a extensão (dev extension enquanto não estiver no registry):

  1. Cmd+Shift+P → zed: install dev extension → selecione zed-valence/.
  2. Abra um .val; diagnósticos, hover, completion, formatter e code actions vêm do servidor.
  3. Para formatar ao salvar:
"languages": {
  "Val": {
    "formatter": "language_server",
    "format_on_save": "on"
  }
}

Para uso fora de um projeto Mix (ou CI), instale o escript e use valence lsp:

mix escript.install hex valence
valence lsp

O que o LSP entrega

  • hover, completion e diagnósticos (inclusive os do modo estrito em .val);
  • formatação (Cmd+S) e code actions (Cmd+.): # valence:ignore e @impl true;
  • signature help com parâmetros tipados;
  • completion de assigns @nome dentro de ~H"""...""" e hover do tipo;
  • tipos de Ecto/Phoenix/stdlib a partir do beam das deps;
  • payload de PubSub tipado no handle_info a partir dos broadcasts do projeto;
  • snippets de callbacks (mount, handle_event, render, …).

CLI

mix valence.check ["lib/**/*.ex" "lib/**/*.val"]
mix valence.type ARQUIVO:LINHA:COLUNA [--beam-path "..."]
mix valence.lsp

O escript equivalente:

valence check ["lib/**/*.ex" "lib/**/*.val"]
valence type ARQUIVO:LINHA:COLUNA
valence lsp
valence --version

Limites conhecidos

  • É uma análise estática best-effort, não um TypeScript completo: Process.get, código dinâmico e assigns condicionais podem virar dynamic(); declare @spec quando a precisão importar.
  • .val hoje é um módulo por arquivo; .ex não pode depender de um módulo .val em tempo de compilação (struct/macro). Rotas e chamadas em runtime funcionam.
  • HEEx tem hover/completion de assigns, mas ainda não diagnóstico de assign desconhecido.
  • PubSub infere payloads de broadcasts com evento literal e tupla {:evento, payload}; tópicos/eventos dinâmicos ficam de fora.
  • No escript, specs da stdlib podem não estar disponíveis; os tasks do Mix (mix valence.*) têm o ambiente completo.

Detalhes e guia de integração: docs/VAL_AND_ZED.md e GETTING_STARTED.md.

Desenvolvimento

mix deps.get
mix format --check-formatted
mix compile --warnings-as-errors
mix test
mix escript.build

Licença

MIT. Veja LICENSE.