Merge branch 'main' into marcomarquesdc-patch-1

Author: BeyondMagic

Makefile

@@ -1,10 +1,14 @@
 CC = gcc
 LEX = flex
 YACC = bison
-CFLAGS = -Wall
+CFLAGS = -Wall -Wextra -std=c11 -D_POSIX_C_SOURCE=200809L -Isrc -I.
 TARGET = c2lua
 
-SRC = src/main.c
+SRC = src/main.c \
+	  src/ast.c \
+	  src/symbol_table.c \
+	  src/semantic.c \
+	  src/codegen_lua.c
 LEX_SRC = src/lexer.l
 YACC_SRC = src/parser.y
 
@@ -17,11 +21,11 @@ all: $(TARGET)
 $(TARGET): $(LEX_OUT) $(YACC_OUT) $(SRC)
 	$(CC) $(CFLAGS) -o $(TARGET) $(LEX_OUT) $(YACC_OUT) $(SRC) -lfl
 
-$(LEX_OUT): $(LEX_SRC)
+$(LEX_OUT): $(LEX_SRC) $(YACC_HEADER)
 	$(LEX) $(LEX_SRC)
 
-$(YACC_OUT): $(YACC_SRC)
-	$(YACC) -d $(YACC_SRC)
+$(YACC_OUT) $(YACC_HEADER): $(YACC_SRC) src/ast.h src/ast.c
+	cd src && $(YACC) -d --defines=../parser.tab.h -o ../parser.tab.c parser.y
 
 clean:
 	rm -f $(TARGET) $(LEX_OUT) $(YACC_OUT) $(YACC_HEADER)

docs/sprints/3.md

@@ -0,0 +1,179 @@
+## Sprint 3 (D21–D30) — AST, símbolos e semântica básica
+
+### Núcleo semântico unificado: definir AST (expr/stmt/decl/fun), tabela de símbolos com escopos, checagem/conversão int↔float e mensagens de erro com linha/coluna
+
+  - [ ] responsáveis: @Sophiassilva
+  - **Entregáveis obrigatórios:**
+      - `src/ast.h` / `src/ast.c` com a hierarquia de nós (expressões, comandos, declarações, funções) e utilitários de criação/destruição.
+      - `src/symbol_table.h` / `src/symbol_table.c` com pilha de escopos (funções para `enter_scope`, `leave_scope`, `insert_symbol`, `lookup`).
+      - Estrutura de `Type` compartilhada para representar `int`, `float`, `bool`, `char`, ponteiros simples e arrays 1D.
+      - Funções de checagem/promoção (`type_can_assign`, `promote_numeric`) acionadas pelas ações semânticas do parser.
+      - Emissão de erro padrão `Erro [linha:col]: mensagem` com localização do token via `@n` do Bison.
+  - **Passos sugeridos:**
+      - Definir um `enum AstKind { AST_VAR_DECL, AST_ASSIGN, AST_IF, ... }` e structs específicas por categoria (ex.: `AstExpression`, `AstStatement`).
+      - Mapear tokens para tipos internos: ao ver `INT`, criar `TYPE_INT`; ao ver `FLOAT_TYPE`, `TYPE_FLOAT` etc.
+      - Guardar no símbolo `Symbol { const char *name; Type *type; int depth; }` a origem (linha/coluna) para diagnósticos.
+      - Integrar com o parser: cada regra deve construir a AST correspondente e empilhar símbolos quando entrar em um bloco `{}`.
+      - Escrever testes mínimos em `tests/semantic/` que instanciam a Tabela de Símbolos via código C (sem parser) para validar inserções e shadowing.
+  - **Exemplos adicionais:**
+      - **AST:** Para `if (x > 0) { x = x - 1; }`, gerar `If(cond: Binary(op: GT, left: Id("x"), right: Int(0)), thenBlock: Block{ Assign(Id("x"), Binary(MINUS, Id("x"), Int(1))) }, elseBlock: null)`.
+      - **Tabela de símbolos com escopos:**
+        | Escopo | Símbolo | Tipo | Profundidade |
+        |--------|---------|------|--------------|
+        | global | x       | int  | 0            |
+        | if     | y       | bool | 1            |
+      - **Promoção numérica:** `float y = 2 + 3.5;` deve produzir um nó Binário cujo resultado tem `TYPE_FLOAT`, convertendo o `2` para `2.0` automaticamente.
+      - **Mensagem de erro rica:** `Erro [5:3]: variável 'z' não declarada; escopo atual possui {x, y}.`
+
+### Suporte sintático essencial: declarações, atribuições, blocos, if/else, while/for, curto-circuito lógico e comparações (==, \!=, \<, \<=, \>, \>=)
+
+  - [ ] responsáveis: @marcomarquesdc
+  - **Entregáveis obrigatórios:**
+    - Regras no `src/parser.y` cobrindo:
+    - Declaração de variáveis (com inicialização opcional) e de vetores 1D.
+    - Atribuições simples e compostas (ex.: `+=`, se decidirmos suportar, documentar).
+    - Blocos `{ ... }` com criação/destruição de escopo.
+    - Estruturas de controle `if/else`, `while`, `for (init; cond; step)` e `do ... while`.
+    - Operadores lógicos com curto-circuito (`&&`, `||`) e comparações.
+    - Ações semânticas que instanciam nós da AST definidos na tarefa anterior.
+    - Atualização dos tokens na `src/lexer.l` se novos operadores forem necessários (ex.: `<=`, `>=`, `!=` já existem; avaliar `+=`, `-=` etc.).
+    - Casos de teste em `tests/syntax/` validando cada construção (happy path + caso de erro por falta de `;`).
+  - **Passos sugeridos:**
+    - Planejar a precedência/associatividade completa no Bison, incluindo atribuições à direita.
+    - Reutilizar a regra `program` para aceitar múltiplas declarações e funções.
+    - Garantir que `for` seja reescrito em AST como um nó com três componentes (init/cond/update) e um corpo `Block`.
+    - Incluir ações de `yyerror` informando token esperado, aproveitando localizações.
+  - **Exemplo alvo:** além do snippet abaixo, teste `for` com incremento, e `if` aninhados com `&&`/`||` para confirmar curto-circuito.
+  ```c
+  int i = 0;
+  for (; i < 5 && i != 3; i = i + 1) {
+    if (i % 2 == 0) {
+      puts("par");
+    } else {
+      puts("ímpar");
+    }
+  }
+  ```
+
+### Análise Semântica: missão Lua abrangente: variáveis locais, expressões, operadores lógicos, arrays 1D como tabelas, mapeamento de printf/puts, helpers de runtime quando necessário
+
+  - [ ] responsáveis: @Liviarodrigues1
+  - **Entregáveis obrigatórios:**
+      - Módulo `src/semantics.c` com passagens sobre a AST para checar tipos, resolver identificadores e anotar cada nó com tipo final.
+      - Implementação das regras de promoção (int→float, char→int, bool→int quando permitido) e erros quando a combinação é inválida (`int + string`, `if` com expressão não booleana, etc.).
+      - Representação de arrays como vetores Lua (`{}`) incluindo deslocamento +1 no índice.
+      - Funções helper em `runtime/printf.lua` ou similar para cobrir `printf`/`puts` e conversões básicas.
+      - Relatório de semântica (ex.: `docs/relatorios/semantica_sprint3.md`) com casos validados e conhecidos a resolver.
+  - **Passos sugeridos:**
+      - Percorrer a AST pós-parsing: primeiro declaração de variáveis/funções, depois corpo.
+      - Armazenar em cada nó `AstExpression` os campos `type` e flags (`is_const`, `is_lvalue`).
+      - Sempre que gerar Lua, garantir que `&&` e `||` se tornem `and`/`or` e mantenham curto-circuito (uso direto já atende).
+      - Para arrays, converter `arr[i]` em `arr[i + 1]` no código gerado.
+      - Incluir testes: `tests/semantic/pass/*.c` (sem erros) e `tests/semantic/fail/*.c` (erro esperado com golden file da mensagem).
+  - **Exemplos ampliados de tradução C → Lua:**
+      - **Arrays 1D:**
+        ```c
+        int arr[3] = {10, 20, 30};
+        arr[1] = 99;
+        ```
+        ↓
+        ```lua
+        local arr = {10, 20, 30}
+        arr[2] = 99
+        ```
+      - **Curto-circuito com ponteiros simulados:**
+        ```c
+        if (ptr != NULL && ptr->val > 10) { log(ptr->val); }
+        ```
+        ↓
+        ```lua
+        if ptr ~= nil and ptr.val > 10 then
+            log(ptr.val)
+        end
+        ```
+      - **Mapeamento de `printf`:**
+        ```c
+        printf("Valor: %d e %f\n", a, b);
+        ```
+        ↓
+        ```lua
+        print(string.format("Valor: %d e %f", a, b))
+        ```
+
+### Funções completas: traduzir assinaturas e return de C para function Lua, preservar escopos e chamadas
+
+  - [ ] responsáveis: @BeyondMagic
+  - **Entregáveis obrigatórios:**
+    - Tradução de declarações de função para AST (`AstFunction`) com lista de parâmetros, tipo de retorno e bloco corpo.
+    - Geração Lua correspondente em `src/codegen_lua.c` (novo arquivo) ou módulo existente, incluindo:
+    - `local function nome(parametros)` para funções não-`main`.
+    - Função `main` convertida em wrapper `os.exit((function(args) ... end)(arg))`.
+    - Suporte a chamadas (`call`) com coerção de argumentos e verificação de aridade.
+    - Atualização da tabela de símbolos para tratar parâmetros como variáveis do primeiro escopo do corpo.
+  - **Passos sugeridos:**
+    - Durante parsing, capturar lista de parâmetros (`ParamDecl`) e inserir no escopo da função antes de analisar o corpo.
+    - Anotar na AST se a função retorna valor; emitir erro se caminho sem `return` em função não-`void`.
+    - Implementar geração de `return` Lua com conversão de tipos se necessário (`return (tonumber(expr))` nos casos obrigatórios).
+    - Cobrir chamadas aninhadas e recursão, garantindo que símbolos sejam resolvidos.
+  - **Exemplo de tradução C → Lua (com parâmetros e retorno):**
+  ```c
+  float media(float a, float b) {
+    return (a + b) / 2;
+  }
+
+  int main() {
+    float resultado = media(5, 7);
+    return 0;
+  }
+  ```
+  ↓
+  ```lua
+  local function media(a, b)
+    return (a + b) / 2
+  end
+
+  os.exit((function(args)
+    local resultado = media(5, 7)
+    return 0
+  end)(arg))
+  ```
+
+### Garantia de qualidade: testes de semântica (erros de escopo/tipo), golden files de erro, pipeline end-to-end (C → Lua → execução), linemap/diagnóstico e atualização de docs/demo
+
+  - [ ] responsáveis: @andrelopesdesousa
+  - **Entregáveis obrigatórios:**
+      - Estrutura de testes automatizados:
+        - `tests/semantic/pass/*.c` + `.lua` esperados.
+        - `tests/semantic/fail/*.c` + `.err` com mensagens exatas.
+        - Script `tests/run_semantic_tests.sh` usando o binário `c2lua` + Lua 5.4 para validar fim-a-fim.
+      - Relato de cobertura: planilha simples ou markdown indicando quais operadores/constructos possuem testes.
+      - Documentação atualizada (`docs/Guia - Projeto de um compilador.md`) adicionando seção "Como rodar a suíte semântica".
+      - Demonstração (gif curto ou log) anexado em `docs/demo/` mostrando o pipeline `C -> Lua -> execução`.
+  - **Passos sugeridos:**
+      - Reaproveitar `tests/run_expr_tests.sh` como base, extraindo funções comuns em `tests/lib/test_utils.sh`.
+      - Incluir check que compara saída de erro com golden file removendo diferenças irrelevantes (ex.: caminhos absolutos).
+      - Integrar no CI local (target `make test-semantic`) chamando o script de testes + `luac -p` no Lua gerado para validar sintaxe.
+      - Criar casos específicos: variável fora de escopo, retorno faltante, tipo inesperado em `while`, indexação fora de array (detectar ou documentar se não suportado).
+  - **Exemplos de testes:**
+      - **Tipo inválido:** `int x = "hello";` → erro `Erro [1:9]: atribuição int <- string não permitida`.
+      - **Escopo:** `int x = 1; { int y = 2; } y = 3;` → erro `Erro [1:26]: símbolo 'y' não encontrado`.
+      - **Pipeline End-to-End:**
+        1. `./c2lua tests/pass/test_sum.c > build/out.lua`
+        2. `lua build/out.lua` produz `4`.
+        3. Script valida stdout e imprime `PASS test_sum`.
+
+## Critérios de pronto por fase
+
+  - Léxico: todos tokens do MVP reconhecidos; sem vazamentos de memória.
+  - Sintático: AST correta para expressões e comandos principais.
+  - Semântico: checagens básicas de tipos/escopos; mensagens com linha/coluna.
+  - Geração Lua: programas do MVP executam em Lua com mesmo resultado.
+  - Qualidade: testes cobrindo happy path + erros; build reprodutível.
+
+## Referências rápidas
+
+  - Flex: padrões, yytext, yylex, yylval.
+  - Bison: gramática, precedência, $$/$1, yyparse, yyerror.
+  - Lua 5.x: escopo local, funções, tabelas, operadores, print.
+
+Observação: atualize os checkboxes conforme avança e preencha os responsáveis inline.