Contribuir
Como o código está organizado e como adicionar exercícios, testes e funcionalidades.
O lightyear é open source (MIT) e aceita contribuições: correções, exercícios do simulador, suítes de teste para outros projetos. O código está em github.com/nvizble/Lightyear42, e o AGENTS.md é a referência técnica completa.
Arquitetura
Go com Clean Architecture. A regra de ouro: nada de lógica de negócio nos comandos Cobra. Os comandos leem argumentos e flags e chamam os services; os services têm as regras; os repositories falam com a API e com o GitHub Releases.
cmd/ comandos Cobra: só parseiam args/flags e chamam services
cmd/lightyear/ entrypoint (package main)
internal/
api/ cliente HTTP da API da 42 (retries, erros tipados)
auth/ OAuth2 e keyring
cache/ cache local em SQLite
config/ Viper e caminhos (XDG)
models/ domínio
services/ regras de negócio
repository/ acesso à API e ao GitHub Releases
notify/ push via ntfy e o estado do que já foi avisado
update/ download, extração e troca do binário
subjects/ catálogo embutido de PDFs de subjects
exam/ exercícios embutidos e o grader do simulador
tester/ lightyear test: checagens do subject e suítes por projeto
editor/ núcleo do editor: buffer, cursor, viewport, undo
vim/ controller estilo Vim: modos, contadores, motions, operadores
syntax/ realce de sintaxe com Tree-sitter (cgo)
lsp/ cliente LSP (só stdlib)
tui/ Bubble Tea: app, dashboard, editorview, testview
pkg/ só APIs públicas exportáveis
A stack: Go 1.25+, Cobra, Viper, Bubble Tea e Lip Gloss, golang.org/x/oauth2, SQLite sem CGO (modernc.org/sqlite) e Tree-sitter, a única parte em C (por isso o build precisa de um compilador C).
Ambiente de desenvolvimento
Precisa de Go 1.25+ e de um compilador C. Para os testes do internal/tester, também de cc, make, nm, ar e python3 (os testes que dependem deles são pulados se faltarem).
git clone https://github.com/nvizble/Lightyear42.git
cd Lightyear42
make build # compila ./lightyear
make install # instala em ~/go/bin/lightyear
make test # go test ./...
make lint # golangci-lint
make fmt # gofmt (e goimports, se instalado)
make vet # go vet
O CI roda go vet, go test e o build no Ubuntu e no macOS, e o golangci-lint, em todo pull request.
Adicionar exercícios ao simulador
Cada exercício é uma pasta em internal/exam/exercises/rank<NN>/level<N>/<nome>/:
internal/exam/exercises/rank02/level1/first_word/
├── subject.en.txt enunciado em inglês (obrigatório)
├── subject.pt.txt enunciado em português
├── meta.json arquivos a entregar e os argumentos de cada teste
├── ref/ solução de referência, com os mesmos nomes de arquivo de "files"
├── provided/ (opcional) arquivos que a prova entrega, como um header
└── main.c (opcional) main de teste, para exercícios de função
O meta.json lista os arquivos da entrega e, em tests, os argumentos (sem o nome do programa) de cada execução:
{
"files": ["first_word.c"],
"tests": [
[],
["FOR PONY"],
[" lorem,ipsum "],
["a", "b"]
]
}
O grader compila a entrega e a ref/ com cc -Wall -Wextra -Werror e compara a saída padrão das duas em cada teste. Nos exercícios de função, o main.c chama a função e imprime o resultado (veja level1/ft_strlen/).
Um exercício em Python tem "lang": "python", o nome da função em function, um único arquivo .py e, opcionalmente, o que é proibido em forbidden ("sorted" para uma builtin ou um módulo, "list.sort" para um método). Cada teste é uma lista de chamadas, cada uma com os argumentos como expressão Python:
{
"lang": "python",
"files": ["py_cryptic_sorter.py"],
"function": "cryptic_sorter",
"forbidden": ["sorted", "list.sort"],
"tests": [
["[3, 1, 2]", "[]"],
["list(range(500, 0, -1))"]
]
}
O grader roda as chamadas de um teste num processo python3 só e compara o repr() de cada retorno (ou raise <Exceção>) com o da ref/.
Os testes do pacote (go test ./internal/exam/) carregam o catálogo e conferem que toda solução de referência passa nos próprios testes. Um rank novo aparece no lightyear exam list e vale em lightyear exam start --rank <NN>. Se usar material de terceiros, credite em internal/exam/CREDITS.md.
Adicionar uma suíte de testes
Os testes do lightyear test ficam em internal/tester/ e são embutidos no binário:
internal/tester/
├── tester.go a lista de projetos (var projects)
├── runner.go cópia do projeto, make, norminette, nm, compilação das suítes
├── libft.go … um arquivo Go por projeto: as checagens do subject
├── c/lt.h, c/lt.c runtime das suítes em C: fork por caso, malloc instrumentado
├── c/<projeto>/ suítes em C, um arquivo por função
├── py/lt.py runtime das suítes de Python
├── py/moduleNN.py uma suíte por módulo de Python
├── sh/born2beroot.sh o teste do born2beroot (roda sozinho também)
└── testdata/<projeto>/ uma solução de referência de cada projeto
Em C
Cada função tem um arquivo c/<projeto>/<função>.c com uma função lt_suite_<função>(). Os casos usam as macros do lt.h: TEST(nome) roda o corpo num processo próprio e CHECK(condição, formato, ...) falha o caso com a mensagem. O runtime já acusa crash, timeout, vazamento, double free e overflow; lt_alloc_fails() faz cada malloc falhar, um de cada vez.
#include "helpers.h"
void lt_suite_ft_strlen(void)
{
lt_group("ft_strlen");
TEST("ft_strlen(\"hello\")")
CHECK(ft_strlen("hello") == 5, "esperado 5, recebido %zu", ft_strlen("hello"));
}
Cada suíte é compilada sozinha contra o header do aluno, então um protótipo errado derruba só os testes daquela função. Um projeto novo também precisa de um <projeto>.go com as checagens (README, norminette, Makefile, funções permitidas…) e de uma entrada em var projects, no tester.go.
Em Python
Uma suíte é um py/moduleNN.py que define suite(t). O common(t, files, typed) do lt.py faz as checagens que todo módulo tem (entrega, flake8, mypy, type hints, sintaxe); o resto são casos com @t.case("nome") que rodam o código do aluno num processo próprio (t.run, t.py) e conferem com t.expect. Registre o módulo em var projects com pythonModule("NN") (passe os marcadores da raiz, se não for ex0).
Solução de referência e bugs plantados
Toda suíte se testa contra uma solução de referência em testdata/<projeto>/, que tem que passar inteira (TestLibftReferencePasses, TestPythonModulesReferencePasses…).
Para provar que os testes pegam erros, os projetos em C também têm bugs plantados: em libft_test.go, printf_test.go e gnl_test.go, cada caso aplica uma troca de texto na referência (por exemplo, malloc(a + b + 1) vira malloc(a + b)) e confere que o grupo certo falha com o status e a mensagem esperados (KO com “heap overflow”).
{"strjoin forgets the +1",
[]edit{{"part2.c", "malloc(a + b + 1)", "malloc(a + b)"}},
"ft_strjoin", KO, "heap overflow"},
Changelog
Toda mudança visível para quem usa entra no CHANGELOG.md, na seção da próxima versão (a próxima canary ou estável), escrita para o usuário:
## [1.3.0-canary.36] — 2026-10-12
- `lightyear test push_swap`: …
O lightyear --version mostra a seção da versão instalada, e um teste quebra se o arquivo sair desse formato.
Releases
Um push de tag v* dispara o GoReleaser, que publica os binários (Linux, macOS e Windows), o .deb e o checksums.txt no GitHub Releases.
- Canary: as novidades saem como tags
v1.3.0-canary.N, publicadas como pre-release. - Estável: as correções da série estável saem da branch
release/1.2.x.
O build roda num runner macOS: clang para darwin e Zig para Linux (estático, com musl) e Windows. Pull requests que mexem no build (.goreleaser.yaml, o workflow de release, go.mod, go.sum) rodam um build de teste, sem publicar nada.
Pull requests
- Faça um fork e crie uma branch a partir da
main. - Mantenha a mudança pequena e focada: um assunto por PR.
- Rode
make testemake lint. - Adicione a entrada no
CHANGELOG.md, se a mudança for visível. - Abra o PR contra a
mainexplicando o problema e a solução.