Contribuir

Como propor mudanças, e o que cada recurso novo exige.

Começar#

bash

git clone https://github.com/estevam5s/DataForge.git
cd DataForge

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

python3 -m pytest tests/ -q          # 272 testes
python3 exercicios/run_all.py        # 190 exercícios

O estado esperado é tudo verde. Se algo falhar antes da sua mudança, isso é em si um achado que vale reportar.

Por onde começar#

Os itens mais acessíveis do roadmap:

Verificação de exaustividade em match sobre enum — o analisador já conhece os membros
Contrato de trait no analisador estático
Funções novas nos módulos Arcane.*
Mais exercícios, especialmente nos módulos 11–20
Correções na documentação — se algo aqui está errado ou confuso

Adicionar um recurso à linguagem#

Um recurso novo toca seis arquivos, nesta ordem:

#	Arquivo	O que fazer
1	`dataforge/tokens.py`	o `TokenType` e, se for palavra, a entrada em `KEYWORDS`
2	`dataforge/lexer.py`	reconhecer o símbolo
3	`dataforge/ast_nodes.py`	o nó, como `@dataclass` com defaults
4	`dataforge/parser.py`	o método `parse_*`
5	`dataforge/interpreter.py`	`exec_<Nó>` ou `eval_<Nó>`
6	`dataforge/typechecker.py`	`st_<Nó>` ou `ex_<Nó>` — senão o analisador ignora

O que cada recurso exige#

Sintaxe documentada em doc/REFERENCIA.md, incluindo a gramática EBNF
Teste de regressão em tests/test_dataforge4.py
Um exercício didático em exercicios/, se o recurso for ensinável
A suíte existente continuando verde

Cuidado com KEYWORDS#

Toda palavra em KEYWORDS deixa de poder ser identificador. Antes de adicionar uma, confirme que o parser realmente a consome:

bash

grep -c "TokenType.NOVA\b" dataforge/parser.py    # precisa ser > 0

Se for 0, ela só quebra código de usuário sem entregar nada. Sete palavras já foram removidas por esse motivo.

Depois, sincronize doc/REFERENCIA.md §1.6 — há um teste que compara as duas listas.

Mensagens de erro#

Uma mensagem deve dizer o que fazer, não só o que houve:

dataforge

# ruim
"Invalid assignment target"

# bom
"'no' is a reserved keyword and cannot be assigned to. Pick another name."

Quando houver um nome parecido, sugira: o analisador usa difflib para isso.

Estilo#

Sem dependências externas em dataforge/ — a stdlib usa apenas a do Python
Documentação, exercícios e mensagens ao usuário final em português
Comentários do runtime seguem o arquivo: inglês nos antigos, português nos módulos 4.0

Antes de abrir o PR#

bash

python3 -m pytest tests/ -q
python3 exercicios/run_all.py
dataforge fmt . --check
dataforge check .