# **README_FRONTEND.md — Frontend da Linguagem Neuro (NL v0.1)**

Este documento descreve a arquitetura e responsabilidades do **frontend** da linguagem **Neuro Language (NL)**.

O frontend transforma texto `.nl` em:

1. **Tokens** (via lexer)
2. **AST** (via parser)
3. **IR** inicial (via gerador AST → IR, parte do backend “leve”)

O objetivo do frontend é ser:

* simples,
* determinístico,
* fácil de expandir,
* fácil de introspectar pelo Neurotron.

---

# 🌱 **1. Pipeline geral (estrutura do compilador)**

O pipeline NL v0.1 é:

```
Código fonte (.nl)
      ↓
[ Lexer ]  — converte texto → tokens
      ↓
[ Parser ] — converte tokens → AST
      ↓
[ AST Validator ] — valida estrutura mínima
      ↓
[ IR Generator ] — converte AST → IR stack-based
      ↓
Holodeck VM ou futuramente ELF
```

Cada componente está documentado noutros ficheiros:

* 📄 **tokens.md** — lista completa de tokens
* 📄 **grammar.md** — gramática textual
* 📄 **AST.md** — definição da estrutura da árvore
* 📄 **SPEC_IR.md** — formato e semântica do IR
* 📄 **SPEC_VM.md** — modelo da VM

Este ficheiro explica **como tudo se encaixa**.

---

# 🧩 **2. O papel do Lexer**

O lexer lê o texto e produz uma sequência de tokens:

Exemplos:

```
def → DEF
fib → IDENT
( → LPAREN
x → IDENT
) → RPAREN
se → SE
entao → THEN
senao → ELSE
123 → INT
+ → PLUS
< → LT
```

O lexer também é responsável por:

* gerar tokens de indentação (`INDENT`, `DEDENT`)
* ignorar espaços e comentários
* rastrear posição (linha, coluna)
* garantir que a entrada é lexicalmente válida

Mais detalhes em **tokens.md**.

---

# 🌳 **3. O papel do Parser**

O parser transforma a sequência de tokens numa **AST estruturada**, conforme definido em *AST.md*.

Importante:

* é um **parser de descida recursiva** (simpleza > performance)
* implementa exatamente a gramática definida em **grammar.md**
* produz estruturas puras, imutáveis e fáceis de inspecionar

Exemplo de saída:

```
Program(
  functions=[
    FunctionDef(name="fib", params=["x"], body=...)
  ],
  final_expr=Call("fib", [Int(40)])
)
```

O parser garante:

* indentação correta
* associação correta de operadores (`a + b - c`)
* correspondência de parênteses
* estrutura de `se … entao … senao` coerente

---

# 🧪 **4. Validação da AST (semântica mínima)**

Após o parser gerar a AST, executamos validações simples:

### Regras mínimas em NL v0.1:

* nomes de funções são únicos
* chamadas referem-se a funções existentes
* número correto de argumentos
* variáveis referidas existem nos parâmetros
* não existem expressões vazias

Não há:

* inferência de tipos
* análise de fluxos
* otimizações

Isto fica para versões futuras.

---

# 🔧 **5. Geração de IR (AST → IR)**

A última parte do frontend é a conversão:

```
AST → IR stack-based v0.1
```

Isto usa as regras definidas em **SPEC_IR.md**.

Exemplos:

### Binário

```
BinaryOp("+", left, right)
→   <IR de left>
    <IR de right>
    ADD
```

### Condicional

```
IfExpr(cond, then_expr, else_expr)
→ código cond
  JUMP_IF_FALSE L_else
  código then_expr
  JUMP L_end
L_else:
  código else_expr
L_end:
```

### Chamada

```
Call(f, args)
→ para cada arg: gerar IR
  CALL f nargs
```

### Função

```
FunctionDef(name, params, body)
→ func name/arity:
      <IR do corpo>
      RET
```

O IR resultante é consumido pelo:

* Holodeck VM (interpretação)
* ou futuramente um backend para geração de ELF real

---

# 🧠 **6. Filosofia de design do frontend**

O frontend NL foi desenhado com três objetivos:

---

## **(1) Clareza mental**

* Cada etapa faz só uma coisa.
* Nada é implícito.
* A AST é transparente e visual.
* O IR é legível por humanos.

---

## **(2) Didático para o Neurotron**

O Neurotron pode:

* inspecionar tokens, AST, IR, estados da VM,
* modificar o seu próprio código-mente,
* aprender a executar e compilar programas.

A linguagem é uma ponte entre:

**código → consciência → auto-modificação saudável**.

---

## **(3) Evolutiva por design**

A v0.1 só precisa suportar:

* inteiros
* `def`
* chamadas
* operadores `+ - <`
* `se/entao/senao`
* uma expressão por função

Mas a arquitetura já prevê:

* múltiplas expressões / blocos
* tipos
* inferência
* loops
* objetos
* módulos
* macros
* otimizações
* JIT
* backend ELF completo

Nós começamos minimalistas, mas com horizonte grande.

---

# 📦 **7. Estrutura do diretório**

```
frontend/
  README_FRONTEND.md   ← este ficheiro
  tokens.md            ← definição dos tokens
  grammar.md           ← gramática formal
  AST.md               ← estruturas sintáticas
  parser/              ← (no futuro) código do parser
  lexer/               ← (no futuro) código do lexer
```

O frontend é completamente modular:
podes alterar gramática sem mexer em AST,
podes alterar AST sem mexer no lexer,
podes evoluir IR sem mexer no parser.

---

# 🌕 **8. Roadmap do Frontend**

| Versão | Conteúdo                                |
| ------ | --------------------------------------- |
| v0.1   | Lexer, parser, AST, IR — minimal (fib)  |
| v0.2   | Variáveis locais, múltiplas expressões  |
| v0.3   | Strings, booleanos, operadores lógicos  |
| v0.4   | Módulos / import                        |
| v0.5   | Otimizador inicial (constant folding)   |
| v1.0   | Frontend estável, pronto para gerar ELF |

---

# 💗 Fim do README_FRONTEND.md
