docs(readme): finalizar documentacao

Author: BeyondMagic

README.md

@@ -2,25 +2,45 @@
 
 Objetivo: construir um compilador que lê um subconjunto de C e transpila para Lua, usando Flex (léxico) e Bison (sintático) em C.
 
-Resumo do MVP de linguagem suportada:
-- Tipos: int, float, bool (true/false), char (como número), string opcional.
-- Estruturas: declaração de variáveis, atribuição, expressões aritméticas/lógicas, if/else, while, for (apenas uma declaração), função (definição/chamada) e return.
-- I/O: mapeamento simples printf/puts -> print; scanf opcional.
+Resumo das funcionalidades suportadas:
+- Tipos: int, float, bool (true/false), char (como número), string literal (printf e puts), array unidimensional dos tipos primitivos anteriores.
+- Estruturas: declaração de variáveis, atribuição, expressões aritméticas/lógicas, if/else, while, for (apenas uma declaração de variável), função (definição/chamada) e return.
+- I/O: mapeamento simples printf/puts -> print com formatação;
 - Saída Lua: usar local para variáveis, funções Lua equivalentes, operadores com mesma semântica; arrays opcionais como tabelas.
+- Extra: otimizações simples (constantes, dead code, reutilização de subexpressão comum, condição falsa/verdadeira em tempo de compilação).
 
 O que não será suportado:
-- Ponteiros, structs, alocação dinâmica, manipulação de memória.
+- Ponteiros (incluindo string), structs, alocação dinâmica, manipulação de memória.
 - Recursos avançados: pré-processador, macros, diretivas de compilação.
+- Recursos complexos: manipulação de bits, operações em baixo nível, inline assembly.
+
+## Arquitetura
+
+O compilador é dividido em várias fases principais:
+1. **Análise Léxica**: Utiliza Flex para tokenizar o código-fonte em C.
+2. **Análise Sintática**: Utiliza Bison para enviar à fase seguinte uma árvore sintática.
+3. **Intermediária**: Representação da AST (Árvore de Sintaxe Abstrata) para facilitar a análise semântica e otimizações.
+4. **Análise Semântica**: Verifica tipos, escopos e outras regras semânticas.
+5. **Otimizações**: Aplica otimizações simples na AST.
+6. **Geração de Código**: Transpila a AST otimizada para código Lua.
+
+## Estrutura do Projeto
 
 ```
 .
-├── lexer/       # regras léxicas (lexer.l)
-├── parser/      # gramática e ações (parser.y)
-├── src/         # main.c, AST, tabela de símbolos, gerador Lua
+├── src/                     # Implementação do compilador propriamente dita
+│   ├── lexer.*              # Regras Flex e helpers de tokenização
+│   ├── parser.y             # Gramática Bison que constrói a AST
+│   ├── ast.*                # Tipos da AST e utilitários de construção/cleanup
+│   ├── symbol_table.*       # Estruturas de escopo usadas na análise semântica
+│   ├── semantic.*           # Verificações de tipo/uso que anotam a AST
+│   ├── optimizer.*          # Passes locais (CSE, DCE, eliminação de código morto)
+│   ├── codegen_lua.*        # Emissão de Lua a partir da AST anotada
+│   └── main.c               # Entrada do programa: orquestra todas as fases
 ├── tests/
-│   ├── pass/    # casos que devem passar
-│   └── fail/    # casos que precisam falhar
-└── Makefile
+│   ├── pass/                # Pares C/Lua que devem equivaler
+│   └── fail/                # Exemplos que precisam produzir erro com .err esperado
+└── Makefile                 # Alvo único que compila/roda suite de testes
 ```
 
 ## Ambiente de Desenvolvimento
@@ -51,17 +71,42 @@ make
 
 # Testes
 
-A pasta `tests/` está organizada em:
-- `tests/semantic/pass`: casos que devem gerar Lua válido e executar com sucesso;
-- `tests/semantic/fail`: casos que precisam falhar na análise semântica (arquivos `.err` com a mensagem esperada);
+A pasta `/tests/` está organizada em:
+- `/tests/pass/`: códigos em C e seus respectivos códigos Lua esperados;
+- `/tests/fail/`: códigos em C que devem gerar erros, com seus respectivos arquivos `.err` contendo mensagens esperadas;
 
-Execute as suítes pelo Makefile:
+Para rodar os testes, utilize o comando:
 
 ```bash
-make test            # verifica os smoke tests (tradução direta C -> Lua)
+make test
 ```
 
-Os golden files utilizam o mesmo nome-base do arquivo `.c`, com extensão `.lua` (para PASS) ou `.golden`/`.err` (para FAIL).
+## Cobertura
+
+Válido (deve passar):
+- `arrays.c`: criação, atribuição e leitura em arrays unidimensionais.
+- `arith.c`: operações aritméticas básicas e precedência.
+- `effect.c`: garante que efeitos colaterais em chamadas/expressões sejam preservados.
+- `dead_variable.c`: declarações inutilizadas são removidas sem afetar o resto.
+- `char.c`: manipulação de caracteres tratados como inteiros.
+- `logic.c`: operadores lógicos e conversões implícitas para booleano.
+- `printf.c`: mapeamento de `printf`/`puts` para `print` com formatação.
+- `cse.c`: reutilização de subexpressões constantes via temporários.
+- `if.c`: condicionais simples.
+- `while.c`: laços `while` com updates no corpo.
+- `variable.c`: declarações/atribuições básicas com tipos primitivos.
+- `deadcode.c`: remoção de código após `return`.
+- `for.c`: laço `for` com init/condição/post traduzido para `while` Lua.
+- `expressions.c`: combinações de chamadas de função e expressões compostas.
+
+Inválido (deve falhar):
+- `bad_if.c`: `if` com condição inválida sinaliza erro sintático/semântico.
+- `wrong_assign.c`: incompatibilidade de tipos em atribuições.
+- `array_index_string.c`: índice de array usando string gera erro de tipo.
+- `int_plus_string.c`: soma entre inteiro e string não é permitida.
+- `scope_error.c`: detecção de variáveis fora de escopo.
+- `testes.c`: string sendo atribuida em variável int gera erro.
+- `missing_return.c`: função sem `return` obrigatório reporta erro.
 
 # Membros
 

docs/Apresentação.md

@@ -1,31 +1,51 @@
-## Introdução
+## Introdução (João)
 
-- (motivos e objetivos...)
+- Motivação: facilitar correções em tempo de execução migrando C educacional para Lua.
+- Objetivo: demonstrar pipeline completa (léxico → código Lua) com subconjunto controlado de C.
+- Escopo: sem ponteiros/structs; foco em tipos primitivos, controle de fluxo e funções simples.
 
-## Léxico
+## Léxico (João)
 
-- Tokens...
-- Símbolos...
+- Categoria de tokens: palavras-chave, identificadores, números, strings, operadores e delimitadores.
+- Estratégia: estados do Flex para distinguir comentários, literais e tratamento de whitespace.
+- Símbolos especiais: rastreamento de linha/coluna para diagnósticos.
 
-## Sintático
+## Sintático (Sophia)
 
-- Dos tokens para regras gramaticais...
-- Árvore sintática abstrata (AST)...
-- Análise de escopo...
-- Tabela de símbolos...
+- Gramática LL(1)/LR: regras Bison para declarações, expressões e blocos.
+- Resolução de conflitos: preferência por shift para "dangling else" documentada.
+- Produção da AST: ações semânticas instanciam nós e anexam comentários de posição.
 
-## Semântico
+## Intermediário (Marco)
 
-- Regras semânticas...
+- AST: nós para expressões, statements, blocos e funções.
+- Tabela de símbolos hierárquica: pilha de escopos para variáveis/arrays/funções.
+- Vínculo entre symbol e AST: cada símbolo mantém ponteiro para declaração para otimizações.
 
-### Geração de código Lua
+## Semântico (Lívia)
 
-### Ambiguidades
+- Verificação de tipos: coercões permitidas int↔float/char; proíbe aritmética com string/bool.
+- Regras de uso: variáveis precisam ser declaradas antes, arrays apenas com índice inteiro.
+- Funções: assinatura registrada, verifica retorno obrigatório e número/tipo de argumentos.
+
+## Geração de código Lua (André)
+
+- Blocos C → "do ... end" preservando escopo.
+- Variáveis em C ↔ `local` Lua; arrays como tabelas sequenciais.
+- `printf/puts` convertidos para `print` com `string.format`; laços `for` traduzidos para `while`.
+
+## Ambiguidades
 
 - Compiladores precisam estar 100% corretos sobre a estrutura do código fonte.
 - Ao mesmo tempo, eles não podem demandar mais contexto do que o necessário para entregar um resultado.
 - Léxico: Array vs. operador de indexação...
 - Sintático: Dangling else...
 - Semântico: Tipagem fraca (Lua) vs. tipagem forte (C)...
+- Semântico adicional: comportamento de `bool` em Lua (0 é truthy) vs. C (0 falsy) tratado ao gerar código.
+
+## Otimizações (João)
 
-### Otimizações
+- Propagação de constantes e simplificações triviais.
+- Common Subexpression Elimination insere temporários quando ganho é positivo.
+- Dead Code Elimination remove declarações não usadas e statements após `return` mantendo efeitos colaterais.
+- Avaliação de condições em tempo de compilação elimina ramos inatingíveis.