@loom-forge/check 0.1.0

package/README.md

@@ -0,0 +1,444 @@
+# @loom-forge/check
+
+A camada de **TIPOS**. Dev/CI, **nunca no hot path de render** (ADR-206). Prova compatibilidade
+estrutural por `subtype` do TSLite — é type-check, não validação de valor (ajv/zod).
+
+```bash
+pnpm add -D @loom-forge/check
+```
+
+Três superfícies, e elas respondem perguntas diferentes — duas precisam de dados, uma não.
+
+| superfície                              | pergunta                                                         | precisa de dados? |
+| --------------------------------------- | ---------------------------------------------------------------- | ----------------- |
+| `checkTree`                             | as props RESOLVIDAS cabem no `descriptor.schema`?                | sim               |
+| `checkComponent` / `checkExpression`    | as EXPRESSÕES tipam — e o call-site passa o que o chamado exige? | não               |
+| `componentType` / `componentAssignable` | a ÁLGEBRA de tipo de um componente (a base dos slots tipados)    | não               |
+
+## Com dados: `checkTree` — props resolvidas ≤ `descriptor.schema`
+
+```ts
+import { createTsliteChecker, checkTree } from "@loom-forge/check";
+
+const checker = createTsliteChecker();
+checker.assignable({ name: "Ana" }, propsJsonSchema); // forma do valor ≤ tipo do schema?
+checker.subtype(typeA, typeB); // A atribuível a B (Schema do TSLite)
+checkTree(resolved, registry, checker); // props de cada nó ≤ descriptor.schema
+```
+
+| Membro                                                   | O quê                                                          |
+| -------------------------------------------------------- | -------------------------------------------------------------- |
+| `subtype(a, b)`                                          | atribuibilidade estrutural (port `TypeChecker`)                |
+| `assignable(value, jsonSchema)`                          | `inferValue(value)` ≤ `fromJsonSchema(jsonSchema)`             |
+| `inferType` · `fromJsonSchema`/`toJsonSchema` · `format` | pontes e diagnóstico                                           |
+| `checkTree(node, registry, checker)`                     | walk + valida props vs `descriptor.schema` → `DataflowIssue[]` |
+
+Roda sobre a árvore RESOLVIDA, então infere a forma dos valores que de fato chegaram — pega
+inclusive o que veio de expressão. Em troca, precisa de dados (uma amostra, uma fixture).
+
+## Sem dados: `checkComponent` — as EXPRESSÕES, estaticamente
+
+```ts
+import { buildEnv, checkComponent, checkExpression } from "@loom-forge/check";
+
+const env = buildEnv(def); // as raízes: props, state (e `data`, se você declarar o tipo)
+checkComponent(def, env); // → CheckIssue[]
+```
+
+Não se reimplementa typecheck: o componente é **baixado** num corpo de função TSL e o
+`@tslite/checker` tipa. Daí saem de graça o scope-flow e a inferência — o tipo do item de um
+`each` vem **inferido da coleção**, sem anotação nenhuma.
+
+```jsonc
+{
+  "each": "{{ props.itens }}",
+  "as": "item",
+  "props": { "n": "{{ item.nomee }}" },
+}
+// → no-such-member: Property 'nomee' does not exist on type '{ nome: string; ativo: boolean }'
+```
+
+| pega                                    | exemplo                                                  |
+| --------------------------------------- | -------------------------------------------------------- |
+| campo inexistente numa raiz             | `{{ props.tituloo }}` · `{{ state.abertoo }}`            |
+| membro inexistente no item de um `each` | `{{ item.nomee }}` — tipo inferido da coleção            |
+| nome sem raiz                           | `{{ titulo }}` → `unknown-name` (não há escopo achatado) |
+| `when` que não rende `boolean`          | `not-assignable` — em vez de um nó sempre-visível        |
+| método de protótipo                     | `{{ xs.length }}` → erro; a forma é `{{ length(xs) }}`   |
+
+Cada issue traz três níveis de proveniência, e eles são independentes:
+
+| campo     | o quê                                                                  | quando existe                       |
+| --------- | ---------------------------------------------------------------------- | ----------------------------------- |
+| `path`    | o campo, como LISTA — `[0, 1, "props", "children"]`                    | **sempre**                          |
+| `address` | o mesmo, como o autor o lê — `#0.1.props.children`. Derivado de `path` | **sempre**                          |
+| `source`  | o texto do campo, como o autor o escreveu                              | quando o campo era TEXTO            |
+| `span`    | `{ from, to }` dentro de `source` (a palavra)                          | idem, e se o nó acusado tem posição |
+
+No `path`, índice e chave são distintos no tipo (`2` anda em array, `"2"` em objeto), e é ele
+que um serviço de linguagem traduz para a coordenada do documento; o `address` é exibição, e
+ninguém o lê de volta. Na árvore a raiz é o nó `0` (`#0.1…`); fora dela o caminho é o do slot
+(`["updates", "somar", "set", "n"]`, `updates.somar.set.n`).
+
+`source.slice(span.from, span.to)` é o trecho aceso — sem compensação nenhuma, inclusive numa
+string mista: o span já leva o deslocamento da ilha dentro do texto, e é a forma do `Span` do
+`@tslite/language-service`, que é o que uma superfície consome. Uma definição
+**já compilada** também tipa (a ilha é decodificada em nós nossos), e aí o issue vem com endereço
+e sem span: a posição não existe, e inventá-la seria pior que não tê-la.
+
+**A string é derivada uma vez.** O check tipa a definição COMPILADA — a mesma que o bind executa
+— e as ilhas em memória que a compilação guardou, com posição no texto do campo. Quem já compilou
+(a bancada, um serviço de linguagem) passa o artefato, e nada é derivado de novo:
+
+```ts
+import { compile } from "@loom-forge/tslite/compile";
+import { compileDefinition } from "@loom-forge/forge";
+
+const compiled = compileDefinition(def, compile); // { def, diagnostics, islands }
+checkComponent(def, env, { compiled }); // só o que é de TIPO
+```
+
+Os diagnósticos da compilação (sintaxe, ilha vazia, o que o profile do deploy recusa) são de quem
+compilou: com `compiled`, o check não os repete. Sem `compiled`, ele compila — sem profile, porque o
+eixo de sintaxe não é dele — e os reporta junto. Um campo que não compilou entra como ausência de
+valor, não como o texto que ficou nele: tipá-lo seria uma cascata do erro que a compilação já
+acusou.
+
+**`checkExpression(source, env, path, { resultType, limits })`** é o cano por slot — o que um
+drawer de editor liga quando o autor abre um campo. Roda por tecla digitada, daí os `limits`; e
+sintaxe quebrada vira diagnóstico (`parse-error`), nunca exceção na cara de quem está digitando.
+
+**`analyzeComponent(def, env, opts)`** é o `checkComponent` sem a projeção: devolve os `issues` e
+o que os produziu — o `Lowered`, o `CheckResult` do corpo (o `overlay` de tipo e escopo por nó) e
+o `Env` dos `init`. É o que um serviço de linguagem consome para responder o **escopo de um
+campo** sem tipar de novo: o `Lowered.frames` diz, por nó (`#0.1`) e por update (`updates.x`), o
+bloco do corpo baixado em que os slots daquele lugar foram emitidos, e o `scopeAt` do
+`@tslite/checker` sobre esse bloco é o escopo — o item do `each`, os `params` — pela mesma
+passada. É o que o `@loom-forge/language-service` faz.
+
+`lowerComponent(def, { compiled })` é exportado para prova e tooling: devolve o `program` (o AST
+baixado), as `anchors` (nó → caminho, por identidade), os `texts` (endereço → o texto do campo),
+os `frames` e as `islands` (as raízes tipadas). Para LER o que está sendo tipado,
+`print(program)` do `@tslite/printer` — imprimir é saída, nunca passo do pipeline: o corpo é
+**construído** com builders e entregue direto ao checker, e é isso que faz a âncora funcionar por
+identidade de nó (ADR-210, ADR-218, ADR-219).
+
+---
+
+## A fronteira do `unknown` — o asserter, não o cast
+
+Não saber o tipo de algo **não é errado**; `any` é. O certo é `unknown`, e a única ponte de
+`unknown` para tipado é o **asserter**: tipa em build e **prova em runtime**. `as` não existe
+aqui — seria tipar sem prova —, e o checker o recusa: `{{ (props.bruto as Endereco).cep }}` é
+`narrowing-cast-not-allowed` no campo, e `as any` é `any-not-allowed`. A régua vem do
+`types.strict` do profile do deploy (`checkComponent(def, env, { profile })`, default o
+`DEFAULT_PROFILE` do bind); do profile o `check` aplica só o eixo de tipos — o que a expressão pode
+conter é acusado pela compilação (ADR-217). O veredito é o mesmo nos dois canos — o campo por
+tecla (`checkExpression`) e o componente inteiro —, porque a ilha da definição compilada é o nó
+como está, com o `as` aninhado dentro. Só um cast **na raiz** (`{{ props.x as T }}`) não chega a
+tipo nenhum: a compilação o recusa como `island-not-a-value`, porque um cast não computa nada.
+
+Passe o catálogo de tipos nomeados e ele nasce:
+
+```ts
+const Address = s.object({ cep: { type: s.string }, city: { type: s.string } });
+const env = buildEnv(def, { types: { Address } });
+
+// {{ parseAs(Address, props.bruto).city }}     → string          ✅
+// {{ parseAs(Address, props.bruto).cidade }}   → no-such-member  ← o checker volta a morder
+// {{ props.bruto.cidade }}                     → passa: `unknown` navega em silêncio
+```
+
+**Errar a ponte deixou de ser silêncio** (`@tslite/checker` ≥ 0.9): cada forma tem código no nó do
+argumento — `unknown-name` (o nome não existe), `type-as-value`, `not-a-schema`,
+`asserter-needs-name`, `missing-argument`. Um `as` que tome o nome de um tipo do catálogo é
+`shadows-schema`, apontando o campo `as` — o checker o vê porque o lowering faz do `as` um
+**parâmetro** do corpo baixado. E a prova que **só pode falhar** é acusada em build:
+`parseAs(Address, { cep: 1 })` é `unprovable-value` quando o tipo do valor não se sobrepõe ao alvo.
+
+**`parseAs`, e não `parse`:** a stdlib já tem um `parse` — o `JSON.parse`, `(text) => unknown`. O
+nome é o `ASSERTER` que o `@tslite/validate` publica (reexportado como `DEFAULT_ASSERTER`), e um
+tipo do catálogo com o nome de um operador ou de uma raiz é recusado na montagem do `env`
+(`BoundaryError`) — erro de quem monta o sistema, não diagnóstico do programa. Sem `types`, não há
+asserter no `env` e a guarda custa zero.
+
+**A outra metade é do binder, e é do chamador.** Tipar é metade; provar é a outra. As duas saem do
+MESMO catálogo, pelo `createBoundary` do `@tslite/validate`: a metade do checker é o que o
+`buildEnv` monta por dentro; a de runtime, o host entrega ao binder:
+
+```ts
+import { createBoundary } from "@tslite/validate";
+import { vanilla } from "@tslite/operators";
+
+const boundary = createBoundary({
+  types: { Address },
+  reserved: Object.keys(vanilla),
+});
+createTsliteBinder({ boundary }); // `parseAs(Address, x)` valida em runtime
+```
+
+Não embutimos isso: quem não usa asserter não deve pagar o validador, e provisão é do host — a
+mesma doutrina do `ActionPort`.
+
+---
+
+## O call-site — `props passadas ≤ props declaradas`
+
+A tese é "B exige/muda um param → A, que compõe B, quebra". Ligue o resolvedor e ela fecha:
+
+```ts
+import { buildEnv, checkComponent, declaredPropsOf } from "@loom-forge/check";
+
+checkComponent(def, buildEnv(def), { propsOf: declaredPropsOf(systemIR) });
+```
+
+```jsonc
+{ "type": "Greeting", "props": { "name": "{{ props.qtd }}" } }
+// → not-assignable @ #0.props.name    — `number` não cabe em `name: string`
+```
+
+| o que passava como `any`                                 | agora                                      |
+| -------------------------------------------------------- | ------------------------------------------ |
+| prop vinda de `{{ }}` com o tipo errado                  | `not-assignable`, no CAMPO, com o span     |
+| a mesma prop dentro de um `each` (usando o item do laço) | idem — o escopo do laço existe no lowering |
+| prop que o chamado NÃO declara                           | `excess-property`, ancorado na **chave**   |
+| prop obrigatória faltando                                | `not-assignable`, no OBJETO (é sobre ele)  |
+| a mesma coisa numa definição já COMPILADA                | idem, com endereço e sem span              |
+
+**Sem `propsOf`, nenhum call-site é tipado** — e não "todos falham". Quem baixa o componente só
+para ver o corpo não tem sistema para perguntar, e inventar um erro ali esconderia o que essa
+pessoa foi olhar.
+
+> [!WARNING]
+> **Prop extra deixou de ser aceita.** Antes o call-site era provado por `subtype` sobre o objeto
+> inteiro, e o subtyping estrutural aceita largura a mais. Agora é o motor que prova, com a regra
+> que o `tsc` aplica a um literal de objeto: uma prop que o chamado não declara é `excess-property`.
+> Num nocode ela é peso morto que o autor não consegue ver — o componente simplesmente a ignora.
+
+**Varrer o sistema inteiro** é o laço, e ele é curto — cada componente tem o seu `env`:
+
+```ts
+for (const def of registry.list())
+  issues.push(...checkComponent(def, buildEnv(def), { propsOf }));
+```
+
+---
+
+## As DECLARAÇÕES — um `TypeRef` que não resolve é erro, não `any`
+
+```jsonc
+{ "props": { "n": "numero" } }
+// → unknown-type-name @ props.n
+```
+
+Era o furo mais caro que restava: o shorthand com typo virava `any`, e `any` **desliga toda a
+prova daquela prop** — call-site, membro, span. Um erro de digitação na declaração apagava a
+máquina inteira sem dizer nada. Agora o que não resolve vira `unknown` (o programa se obriga a
+lidar) e o `checkDeclarations` diz **qual nome** não existe, no endereço da declaração
+(`props.n`, `state.aberto`).
+
+Um nome do **catálogo** vale como `TypeRef`: com `types: { Address }`, `"props": { "addr":
+"Address" }` resolve. Sem o catálogo, o mesmo nome é reportado — e isso é o certo, porque dali
+ele de fato não existe.
+
+### O `init` do estado — provado no escopo que SEMEIA
+
+```jsonc
+{
+  "state": {
+    "email": { "type": "string", "init": "{{ props.perfil.email }}" },
+  },
+}
+```
+
+O `init` é expressão, avaliada **uma vez, no mount** — a semântica do `useState(props.x)`. Ele é
+tipado num `Env` PRÓPRIO (`buildInitEnv`): só `props` e `ctx`, sem `state` (é o que está sendo
+definido) e sem `params` (não há chamada). É a mesma projeção que o runtime passa ao `initState`,
+e é por isso que ele não divide o env do corpo:
+
+| escrito no `init`     | o que acontece                                               |
+| --------------------- | ------------------------------------------------------------ |
+| `{{ props.inicial }}` | tipa contra o `type` declarado, no endereço `state.<k>.init` |
+| `0`                   | constante atravessa intacta                                  |
+| `{{ state.valor }}`   | `unknown-name` — em runtime ele nem existe ali               |
+
+> [!WARNING]
+> Antes disto, o `init` **não passava por nada**: nem compilação, nem bind, nem typecheck. Um
+> `"{{ props.x }}"` ali virava texto literal na tela, e `{ "type": "number", "init": "abc" }`
+> passava. Os dois silêncios fecharam juntos.
+
+---
+
+## Os UPDATES LOCAIS — o `set` é um call-site sobre o ESTADO
+
+É a perna que fechava o anel: props entram, `state` é lido, e aqui ele é **escrito**.
+
+```jsonc
+{
+  "state": { "count": { "type": "number", "init": 0 } },
+  "updates": {
+    "add": {
+      "params": { "n": "number" },
+      "set": { "count": "{{ state.count + params.n }}" },
+    },
+  },
+}
+```
+
+| erro                                           | onde pousa                         |
+| ---------------------------------------------- | ---------------------------------- |
+| valor do tipo errado                           | `updates.add.set.count`            |
+| campo que o estado não declara                 | `updates.add.set.<chave>`          |
+| o evento passa um param do tipo errado         | `#0.events.onClick.params.n`       |
+| o evento passa um param que a ação não declara | `#0.events.onClick.params.<chave>` |
+
+O `set` é **parcial**: escrever um campo não obriga a escrever os outros.
+
+**`params` é dado de FORA.** Sem `params` declarado ele vale `unknown` — e escrevê-lo direto num
+estado tipado não passa. Não é aspereza: é a mesma fronteira das props, e declarar é a saída (e
+de quebra tipa o call-site do evento que dispara a ação).
+
+### A ação do HOST também é provada — passe a porta
+
+```ts
+checkComponent(def, buildEnv(def), { actions: port });
+```
+
+A assinatura vem do `paramsOf` do Tier 1 (o `ActionPort`, o commander, ou qualquer objeto com o
+método), em JSON Schema — a borda que o `TypeRef` já atravessa. Com ela, `events.params` de uma
+ação do host vira o mesmo call-site do update local: obrigatória faltando, tipo errado,
+`excess-property` na chave. E a ordem de resolução é a do RUNTIME — **update local primeiro, host
+depois** —, porque um componente com um update chamado `salvar` não alcança a action `salvar` da
+aplicação, e provar contra ela apontaria para um contrato que aquele nome nem toca.
+
+**Sem a porta, a ação do host não é tipada — e isso é silêncio, não erro.** Quem não publica
+assinatura não afirmou nada. A porta tem a outra metade do contrato, o **`resultOf`** — a forma
+do RETORNO —, e é ela que tipa o `event` de um `then` (abaixo).
+
+### `resolve` — o que a camada de COMANDO preenche
+
+```jsonc
+{ "events": { "onClick": { "action": "lead/open", "resolve": ["id"] } } }
+```
+
+Um comando resolve param por token (`$focus`), por default, ou **perguntando** — abrindo um drawer,
+um seletor. Isso é legítimo, e é diferente de esquecer. Então se declara:
+
+| o param…                       | o que acontece                        |
+| ------------------------------ | ------------------------------------- |
+| foi passado                    | é provado contra o tipo               |
+| está em `resolve`              | conta como preenchido, e não falta    |
+| não está em nenhum dos dois    | **erro** — obrigatória faltando       |
+| está em `resolve` e não existe | `excess-property`, no campo `resolve` |
+
+É o que impede o default virar sorte. Em runtime o `resolve` **não faz nada**: ele é declaração, e
+quem preenche é o commander, com os resolvers dele.
+
+### O nome de COMANDO — provado contra a ação que ele executa
+
+```jsonc
+{
+  "id": "s",
+  "type": "Section",
+  "commands": {
+    "abrir": { "action": "lead/open", "params": { "motivo": "atalho" } },
+  },
+  "children": [
+    {
+      "id": "b",
+      "type": "Button",
+      "events": { "onClick": { "action": "abrir" } },
+    },
+  ],
+}
+```
+
+O evento é provado contra a ação que o nome EXECUTA, nos degraus da expansão: update local,
+vocabulário de onde o nó monta, porta (ADR-015 do repo). O que o alias já liga conta como
+preenchido. E o próprio alias é provado onde foi escrito, contra a assinatura com tudo opcional,
+porque ele é aplicação parcial: faltar é legítimo, sobrar e errar o tipo não são.
+
+| escrito                                                 | onde pousa                           |
+| ------------------------------------------------------- | ------------------------------------ |
+| o alias liga uma chave com o tipo errado                | `#0.commands.abrir.params.<chave>`   |
+| o alias liga uma chave que a ação não declara           | idem, `excess-property`              |
+| o disparo não passa a obrigatória que o alias não ligou | `#0.0.events.onClick.params`         |
+| o disparo passa uma chave que a ação não declara        | `#0.0.events.onClick.params.<chave>` |
+
+Passe a montagem do sistema, e um filho de slot é provado pelo vocabulário da sessão onde monta:
+
+```ts
+import { mountingOf } from "@loom-forge/forge";
+
+checkComponent(def, buildEnv(def), {
+  actions: port,
+  mounting: mountingOf(sys.components.values()),
+});
+```
+
+**Sem ela, o documento é o sistema:** o que ele declara resolve dentro dele, e o resto vale como o
+id da porta. Com ela, um nome que algum vocabulário declara e o documento não resolve depende de
+onde o componente monta — e não é provado contra assinatura nenhuma. Ver ADR-216.
+
+### O `event` de uma intenção — a ENTRADA de dado, provada (ADR-018 do repo)
+
+```jsonc
+{
+  "events": {
+    "onChange": {
+      "action": "editar",
+      "params": { "campo": "cpf", "valor": "{{ event }}" },
+    },
+  },
+}
+```
+
+Tudo o que uma intenção recebe entra pelo `params`, e `event` é a raiz que o carrega: o que o
+widget emitiu, o `data` da ação anterior num `then`, o `error` num `catch`. O lowering abre um
+frame por intenção com `event` como parâmetro **tipado**, e os `params` são tipados dentro dele:
+
+| onde                       | o tipo de `event` vem de                                                           | sem declaração |
+| -------------------------- | ---------------------------------------------------------------------------------- | -------------- |
+| `events.onX` num widget    | `descriptor.meta.emits.onX` (seam `emitsOf`)                                       | `unknown`      |
+| `events.onX` num `el`      | —                                                                                  | `unknown`      |
+| `then` de uma ação do host | `resultOf(action)` da porta (`actions`)                                            | `unknown`      |
+| `then` de um update local  | `undefined` — o estado foi escrito, e só                                           | —              |
+| `catch`                    | `{ code: string; message?: string; data?: unknown }`, o contrato do `ActionResult` | —              |
+| um efeito (e o `cleanup`)  | `undefined` — nada o emitiu; o `then`/`catch` dele seguem as linhas acima          | —              |
+
+E **`unknown` num param tipado é `not-assignable`**: quem não declarou o que emite (o kit) ou o
+que devolve (a porta) não ganha um tipo de graça — a leniência que o `as` tinha saiu com ele. O
+autor sai disso declarando ou provando (`parseAs`). Cada elo de uma cadeia é um call-site (o
+`params` contra a assinatura da ação que ele executa), e cada `then`/`catch` abre o próprio
+`event`, que sombreia o de fora — como numa promise chain. Os caminhos seguem a cadeia:
+`#0.events.onClick.then.params.valido`, `#0.events.onClick.catch.params.motivo` na árvore;
+`effects.carregar.then.params.user`, `effects.carregar.cleanup.catch.params.motivo` fora dela — é
+o mesmo caminho em que a compilação do `forge` os deixa (`componentSlotsOf`). Um efeito com
+`then` é "carregar no mount e guardar o que carregou", e o `event` desse `then` é o `resultOf`
+da ação, como num evento.
+
+**`pending[ação]`** é raiz do `env` de um componente **vivo** (`updates` ou `effects`):
+`Record<string, boolean>`, `true` do despacho ao resultado. Num componente puro é `unknown-name`,
+e o remédio é o que o torna vivo.
+
+---
+
+## A álgebra de tipo de um componente
+
+```ts
+import {
+  componentType,
+  componentAssignable,
+  declaredPropsOf,
+} from "@loom-forge/check";
+
+componentType(ir); // { props: Schema, category?, tags, entry }
+componentAssignable(child, { props }); // child ≤ Component<C> no eixo de props
+declaredPropsOf(systemIR); // o resolvedor que liga o call-site (acima)
+```
+
+`TypeRef` (o que a declaração escreve) resolve para `Schema` do TSLite, que é o SSOT: shorthand
+(`"string"`), Schema literal, ou JSON Schema **só na borda** (via `@tslite/jsonschema`). Prop com
+nome terminado em `?` é opcional, TS-like — e opcional aqui significa **`T | undefined`**, porque
+props viajam como JSON e em JSON `undefined` não existe: `{}` e `{ body: undefined }` são o mesmo
+documento (ADR-214).