# 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).
