# Valence como linguagem: `.val` + Zed

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`):

```elixir
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)

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

def project do
  [
    # ...
    compilers: [:valence] ++ Mix.compilers()
  ]
end
```

```bash
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:

```elixir
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:

```elixir
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:

```elixir
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):

```elixir
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.

```elixir
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.

```elixir
# 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

```elixir
@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):

```json
"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:

```elixir
# 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

```bash
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:

```bash
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

| 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ó `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()}`.