Current section
Files
Jump to
Current section
Files
README.md
# Valence
**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:
```elixir
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
```
```bash
mix deps.get
mix compile
```
Requer Elixir **1.20+** (OTP 27+).
## `.val` em 30 segundos
Crie `lib/minha_app/scoring.val`:
```elixir
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`.
```bash
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:
```json
"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`:
```bash
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
```bash
mix valence.check ["lib/**/*.ex" "lib/**/*.val"]
mix valence.type ARQUIVO:LINHA:COLUNA [--beam-path "..."]
mix valence.lsp
```
O escript equivalente:
```bash
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](docs/VAL_AND_ZED.md) e
[GETTING_STARTED.md](GETTING_STARTED.md).
## Desenvolvimento
```bash
mix deps.get
mix format --check-formatted
mix compile --warnings-as-errors
mix test
mix escript.build
```
## Licença
MIT. Veja [LICENSE](LICENSE).