diff --git a/trabalho-raylib/01-discovery/01-software.md b/trabalho-raylib/01-discovery/01-software.md new file mode 100644 index 000000000000..ba3b73e5c2db --- /dev/null +++ b/trabalho-raylib/01-discovery/01-software.md @@ -0,0 +1,57 @@ +# 1.1 — O que é o raylib? + +## Ficha do software + +| Item | Descrição | Evidência | +|---|---|---| +| **Problema que resolve** | Aprender e fazer programação de jogos/gráficos em C sem a complexidade de engines e de toolchains com muitas dependências. Nasceu porque o autor, ao ensinar jogos a alunos sem experiência, achou as bibliotecas existentes (WinBGI) pouco claras e sem aceleração por hardware. | `[L]` `HISTORY.md:6-12` | +| **Público-alvo** | "Prototipagem, ferramentas, aplicações gráficas, sistemas embarcados e **educação**". | `[L]` `README.md:5` | +| **Principais usuários** | Estudantes e professores; desenvolvedores indie/protótipos; autores de *bindings* (+70 linguagens); contribuidores de portes de plataforma. | `[L]` `README.md:53`, `BINDINGS.md`, `CONTRIBUTING.md:5-11` | +| **Principais funcionalidades** | Janela + laço de renderização; entrada (teclado, mouse, gamepad, toque); formas 2D, texturas e texto; modelos 3D e animação; shaders; áudio (WAV, OGG, MP3, FLAC, QOA, XM, MOD); módulo matemático (`raymath`); câmeras; camada de abstração OpenGL (`rlgl`); renderizador por software (`rlsw`). | `[L]` `README.md:35-54` | +| **Tecnologias** | **C99** (PascalCase/camelCase), OpenGL 1.1/2.1/3.3/4.3/ES2/ES3 (ou software), back-ends de plataforma GLFW/SDL/RGFW/Win32/Web/DRM/Android/Memory, bibliotecas *single-header* embutidas (stb, miniaudio, cgltf…), Makefile + CMake + `build.zig`, GitHub Actions. | `[L]` `README.md:39-42`, `src/rcore.c:6-35`, `src/external/`, `.github/workflows/` | +| **Licença** | **zlib/libpng** (permissiva; permite uso comercial e *linking* estático com código fechado). | `[L]` `LICENSE`, `README.md:160`; `[GH]` API → `Zlib` | +| **Versão/release analisada** | Release **6.2** (15/10/2026) e snapshot local do `master` (`RAYLIB_VERSION "6.5-dev"`). Releases anteriores: 6.0 (23/04/2026), 5.5 (18/11/2024). | `[L]` `src/raylib.h:89-92`, `CHANGELOG:4`; `[GH]` releases | +| **Escala** | ~59,6 mil linhas de código próprio em `src/` (sem `external/`), ~266 mil linhas de bibliotecas externas embutidas, 228 arquivos `.c` em `examples/` (README diz "+220"). | `[M]` contagem PowerShell no snapshot | +| **Popularidade (31/10/2026)** | 35.517 estrelas, 3.365 forks, 21 itens abertos (issues + PRs). Criado em 24/10/2013. | `[GH]` `api.github.com/repos/raysan5/raylib` | + + +## Posicionamento: o que o raylib *não* faz + +`[L]` `README.md:56-65`: janela única com um contexto OpenGL; redimensionar/mover pausa o laço em algumas plataformas; +`RenderTexture` vem invertida; rasterização de fontes inferior ao Freetype; **sem RTL, ligaduras ou emojis** no desenho de texto. +Também é filosofia assumida: "sem interface, sem ajudantes visuais, sem botão de debug, só o código" (`README.md:7`). + +## Personas e Jobs to Be Done (JTBD) + + +### Persona 1 — Estudante iniciante de programação de jogos + +- **Quem é:** aluno com pouca ou nenhuma experiência, aprendendo C e lógica por meio de jogos. +- **Evidência:** a própria origem do projeto — alunos "que nunca tinham escrito uma linha de código" programando PONG + (`HISTORY.md:8`); "raylib is designed to be learned using the examples" (`README.md:125`); método "Learn by reading code and examples" (`CONTRIBUTING.md:41-43`); 228 exemplos `[M]`. +- **JTBD:** *Quando* estou começando a programar e quero ver algo na tela logo na primeira aula, *eu quero* abrir uma janela + e desenhar com poucas chamadas e sem instalar dependências, *para que* eu mantenha a motivação e entenda cada linha do que escrevi. +- **Como o software atende:** exemplo mínimo de 5 chamadas (`InitWindow`, `WindowShouldClose`, `BeginDrawing`/`EndDrawing`, `CloseWindow`) em `README.md:70-89`; "NO external dependencies" (`README.md:37`). + +### Persona 2 — Desenvolvedor de protótipos / jogos indie + +- **Quem é:** pessoa que já programa e quer prototipar rápido ou publicar um jogo pequeno em várias plataformas. +- **Evidência:** "prototyping, tooling, graphical applications, embedded systems" (`README.md:5`); suporte a Windows/Linux/macOS/RPI/Android/HTML5 (`README.md:38`); licença zlib permite uso comercial (`CONTRIBUTING.md:22`). +- **JTBD:** *Quando* tenho uma ideia de jogo e pouco tempo, *eu quero* uma biblioteca leve que cubra janela, entrada, 2D/3D e áudio + e compile para várias plataformas, *para que* eu entregue um protótipo jogável sem aprender uma engine inteira. + +### Persona 3 — Contribuidor de portes de plataforma / correção de bugs + +- **Quem é:** desenvolvedor externo que melhora um back-end (ex.: Win32, GLFW, SDL, DRM) ou corrige bugs em funções do núcleo. +- **Evidência:** 6.2 tem **310 entradas** de changelog e **~130 autores distintos**; 77% referenciam um PR `[M]` (`CHANGELOG:7-332`); só o autor `@Ne0nWinds` aparece em **27 linhas** (muitas do back-end Win32, mas também correções do núcleo como `GetFPS()`). `CONTRIBUTING.md:59-64` pede PRs pequenos e "verificar que não quebra o build". +- **JTBD:** *Quando* corrijo um bug ou ajusto uma plataforma, *eu quero* um jeito rápido e automático de confirmar que não quebrei outras funções, + *para que* meu PR pequeno seja aceito com confiança — hoje a única verificação exigida é "o build não quebra" (`CONTRIBUTING.md:63-64`). +- **Relação com a evolução proposta:** esta é a persona principal da proposta de testes (ver `05-evolucao/`). + +### Persona 4 — Autor/mantenedor de *binding* + +- **Quem é:** quem encapsula o raylib para outra linguagem (Python, Rust, Jai, Goose…). +- **Evidência:** `BINDINGS.md` lista bindings com a versão suportada (ex.: `raylib-py 6.2`, `raygoose 6.5-dev`) `[L]`; commits recentes do `master` atualizam essa lista (#6345, #6347, #6350) `[GH]`. +- **JTBD:** *Quando* sai uma nova versão do raylib, *eu quero* saber quais comportamentos da API mudaram (ex.: `-WARNING-` no CHANGELOG), + *para que* eu atualize meu binding sem quebrar usuários. +- **Evidência de dor:** o CHANGELOG 6.2 marca 15 entradas com `-WARNING-` (mudanças de comportamento/API) `[M]`, p.ex. `File*()` com novos valores de retorno e `GetSplinePointBezierQuad()` renomeada. diff --git a/trabalho-raylib/02-processo/02-evolucao-e-processo.md b/trabalho-raylib/02-processo/02-evolucao-e-processo.md new file mode 100644 index 000000000000..54fcc98a274b --- /dev/null +++ b/trabalho-raylib/02-processo/02-evolucao-e-processo.md @@ -0,0 +1,90 @@ +# 2.2 — Como o raylib evoluiu e como é desenvolvido + +## Linha do tempo resumida + +| Data | Marco | Fonte | +|---|---|---| +| 24/10/2013 | Repositório criado | `[GH]` API do repositório | +| nov/2013 | raylib 1.0 ("começou como projeto de fim de semana", 3 meses de trabalho) | `[L]` `HISTORY.md:16` | +| abr/2014 | 1.1 — redesenho interno; nasce o módulo `rlgl` (OpenGL 1.1/3.3/ES2) | `[L]` `HISTORY.md:23-27` | +| set/2014 | 1.2 — redesenho do `core` para Android e Raspberry Pi | `[L]` `HISTORY.md:36-38` | +| 2.0 | Remoção das dependências externas (GLFW3 e OpenAL) | `[L]` `ROADMAP.md:67-68` | +| 18/11/2024 | Release 5.5 | `[GH]` releases | +| 31/03/2025 → 31/08/2025 | PR #4869: back-end nativo Win32 | `[GH]` | +| out/2025 | PRs do renderizador por software `rlsw` | `[GH]` | +| 23/04/2026 | Release 6.0 ("a maior até agora") | `[GH]` releases | +| 15/10/2026 | Release 6.2 | `[GH]` releases | + +## Acontecimentos relevantes + +### A1 — Mudança arquitetural: de um `core` monolítico para back-ends de plataforma + +- **O que mudou:** o `rcore.c` deixou de conter todo o código de janela/entrada por plataforma. A meta "Split core module into separate platforms" + aparece como concluída em 5.0 (`ROADMAP.md:40`). Hoje `rcore.c` seleciona o back-end com `#include "platforms/..."` por macro + (`src/rcore.c:518-533`) e existem 10 arquivos em `src/platforms/` (GLFW, SDL, RGFW, Win32, Web, Emscripten, DRM, Android, Memory + template). +- **Contrato entre núcleo e plataforma:** `InitPlatform()`/`ClosePlatform()` declarados como `extern` em `rcore.c:491-492`; + `rcore_template.c` documenta o esqueleto para novos back-ends (`rcore_template.c:1-69`). +- **Por que importa:** permitiu adicionar plataformas (Win32, Memory, Emscripten) sem reescrever o núcleo — base dos acontecimentos A2 e A3. + +### A2 — Nova funcionalidade grande via contribuição externa: back-end nativo Win32 (PR #4869) + +- **Evidência `[GH]`:** PR #4869 "[rcore][win32] Adding native win32 backend", autor `marler8997`, aberto em **31/03/2025**, mesclado em **31/08/2025** por `raysan5`; + 14 commits, +2.194 linhas, 0 removidas, 8 comentários. O autor justificava com executáveis menores (~0,83× o do GLFW) e menos comportamentos surpreendentes. +- **Evolução posterior (incremental):** correções logo depois — #5297 (reverter mudança indesejada, 23/10/2025), #5299 (mingw), #5311 (Makefile), #5365 (MSVC, 20/11/2025) `[GH]`. + No 6.2, há dezenas de linhas `[rcore][Win32]` (MSAA, clipboard, `IsKeyPressedRepeat`…) `[L]` `CHANGELOG:71-88`, e o `ROADMAP.md:18` ainda lista "Improve new Windows platform backend" para a 7.0. +- **Leitura crítica:** uma funcionalidade de 2 mil linhas ficou 5 meses em revisão e chegou "incompleta mas funcionando" — ou seja, entrega **incremental** com estabilização posterior pela comunidade. + +### A3 — Reversão de decisão de roadmap: renderizador por software (`rlsw`) + +- **Antes:** no roadmap da 4.0, "Software rendering backend (avoiding OpenGL) (#1370) — _DISCARDED_" (`ROADMAP.md:52`). +- **Depois:** na 6.0 vira meta cumprida: "`rlsw`: New Software Renderer backend, pseudo-OpenGL 1.1 implementation" (`ROADMAP.md:33`), e a release 6.0 o descreve como "CPU-only software renderer" `[GH]`. +- **Ritmo:** série de PRs de `Bigfoot71` em out/2025, muitos mesclados em horas: #5304 aberto 25/10/2025 22:47 UTC e mesclado 22:58; #5300 (25/10) e #5312 (28/10) mesclados no mesmo dia em que foram abertos; #5342 aberto 07/11 e mesclado 08/11/2025 `[GH]`. + No 6.2: "Double buffering support… Pico 2", "ESP32 optimizations" `[L]` `CHANGELOG:95-114`. +- **Leitura crítica:** o projeto **muda de ideia com base em necessidade e em contribuição disponível** (aderente ao valor ágil "responder a mudanças"). + +### A4 — Qualidade e segurança: auditoria externa e correção rápida de bug (release 6.2) + +- **Auditoria:** "Multiple security concerns reported by ROS (Radically Open Security)" (`CHANGELOG:13`); ex.: `OpenURL()` com checagens contra URLs maliciosas — `CLN-002` (`CHANGELOG:31`), `LoadAutomationEventList()` — `CLN-005/006` (`CHANGELOG:32`). +- **Bug curto-ciclo — `ComputeSHA256()`:** a função entrou pelo PR **#5264** (`JohnnyCena123`, aberto 13/10/2025, **mesclado 15/10/2025** por `raysan5`); + uma implementação concorrente, PR **#5266** (`manuel5975p`, "alternative implementation"), foi **fechada sem merge** em 02/11/2025 `[GH]` — exemplo de escolha entre alternativas na revisão. + Em **12/09/2026 05:15 UTC** foi aberta a issue **#6143** (hash errado se `tamanho mod 64` ∈ 56..59) e **05:16** o PR **#6144** com a correção, fechado 08:24 do mesmo dia `[GH]`; entra no CHANGELOG 6.2 com `-WARNING-` (`CHANGELOG:42`). + Confirmamos no código atual: `src/rcore.c:3545-3546` reserva 8 bytes do comprimento antes de arredondar para 64 `[L]`. +- **Leitura crítica:** a correção foi rápida, mas o bug foi **descoberto por usuário depois da função publicada** — não por teste do projeto. + +### A5 — Padrão de regressões na mesma função: `GetFileExtension()` + +- PR **#6326** "Fix `GetFileExtension()` returning the name of hidden files…" (aberto 24/10/2026, fechado/mesclado 25/10/2026) e, três dias antes, PR **#6312** "Fix `GetFileExtension()` returning a dot from a directory name" (aberto 21/10/2026) `[GH]`. +- O código atual trata os dois casos (`src/rcore.c:2500-2509`): usa `GetFileName()` para ignorar diretórios e rejeita `dot == name` para arquivos ocultos `[L]`. +- **Observação:** duas correções no mesmo helper em 3 dias sugerem ausência de uma suíte que fixe o comportamento esperado — motivação direta da evolução proposta (`05-evolucao/`). + +## Como o projeto é desenvolvido (práticas observadas) + +| Prática | Evidência | +|---|---| +| **Mantenedor central + comunidade grande** | `raysan5` mescla PRs (ex.: #4869) e escreve ~23% das entradas do 6.2 (70/310) `[M]`; ~130 autores distintos no 6.2 `[M]`. | +| **Contribuição por PR pequeno** | `CONTRIBUTING.md:61-64`: "Don't send big pull requests… send small pull requests, one at a time". | +| **Issues com tag de módulo** | `CONTRIBUTING.md:55-56`: prefixar o título com `[rcore]`, `[rtext]`…; visto em todos os títulos recentes `[GH]`. | +| **Padrão de código documentado** | `CONVENTIONS.md` (tabela de nomes, 4 espaços, sem TAB, comentários antes da linha). | +| **Integração contínua** | 12 workflows em `.github/workflows/`: builds Windows/Linux/macOS/Android/WebAssembly/CMake e dos exemplos; `clang_tidy.yml`, `analyze_codeql.yml` (cron semanal) e `parse_api.yml` (gera `raylib_api.*`). `build_cmake.yml` tem um passo "Test" com `ctest` (`:62-67`, `:106-111`), mas **não há nenhum `add_test()`** no repositório (busca em `.txt/.cmake/.zig/.yml`, fora de `src/external`) — logo não há testes registrados para o `ctest` rodar `[L]` *(inferência: não executamos o CMake)*. | +| **Teste de exemplos (smoke test)** | `tools/rexm` (`rexm test`, `testlog`, `validate`) compila e roda cada exemplo e confere: avisos de compilação/log, inicialização, fechamento, carga de assets, `rlgl`, plataforma, fonte e timer; gera relatórios por plataforma em `tools/rexm/reports/examples_testing_{windows,linux,macos,web,drm}.md` `[L]`. A comunidade complementa com a issue #5664 (22 comentários) pedindo relatos "`[exemplo] - Plataforma`" `[GH]`. **Verifica a biblioteca de ponta a ponta, mas não o resultado das funções** (um exemplo passa mesmo que `ComputeSHA256` retorne hash errado). | +| **Releases com changelog detalhado** | `CHANGELOG` por módulo e tag `[rcore][GLFW]`…, autor e nº do PR em cada linha. | +| **Planejamento aberto** | `ROADMAP.md` + "wishlist" em *Discussions* por versão (7.0: discussão #5710) `[L]`. | +| **Reuso massivo** | `src/external/` com ~266 mil linhas de bibliotecas *single-header* (stb, miniaudio, cgltf, GLFW…) frente a ~59,6 mil linhas próprias `[M]`. | +| **Documentação por exemplos** | 228 exemplos compiláveis; sem documentação formal de API (`README.md:125`). | + +## Relação com processos de software + +> Análise crítica: o raylib **não segue** um modelo prescritivo. Abaixo, o que **se parece** e o que **não se parece** com cada um. + +| Conceito | Aderência | Evidência e crítica | +|---|---|---| +| **Desenvolvimento incremental** | **Alta** | Entregas contínuas em PRs pequenos; releases com changelog (5.5 → 6.0 → 6.2); recursos grandes (Win32, `rlsw`) entram "incompletos mas funcionando" e são refinados depois (A2, A3). **Crítica:** o intervalo entre 5.5 e 6.0 foi de ~17 meses (18/11/2024 → 23/04/2026), longo para um modelo incremental. | +| **Reuso** | **Alta** | `src/external/` embute bibliotecas (stb, miniaudio, cgltf, par_shapes, GLFW…) em vez de reimplementar; `rlgl` e `raymath` são reutilizáveis de forma isolada (`README.md:41,49`); `rcore_template.c` é um gabarito reutilizável para novas plataformas. **Crítica:** reuso custa governança de licenças heterogêneas (ver `07-etica/`) e de atualizações. | +| **Manifesto Ágil / XP (parcial)** | **Média** | *Software funcionando acima de documentação* (exemplos no lugar de docs de API); *responder a mudanças* (A3); *indivíduos e interações* (Discord, Reddit, Discussions); XP: padrão de código (`CONVENTIONS.md`), integração contínua, *small releases*, propriedade coletiva. XP também valoriza testes; o projeto tem *smoke tests* de exemplos (`rexm test`) e testes manuais da comunidade (#5664), um traço de "teste de aceitação" informal. **Crítica — não há testes automatizados das funções da biblioteca (nem TDD):** é o furo mais visível frente ao XP, e o que sustenta a evolução proposta. | +| **Scrum** | **Baixa** | Não há sprints, papéis (PO/SM), *backlog* priorizado nem cerimônias; issues quase sem rótulos (ex.: #6351, #6349, #6342 sem rótulo) `[GH]`. O que existe é um *roadmap* de desejos, não um backlog. | +| **Cascata** | **Nula** | Não há fases sequenciais nem especificação prévia; `ROADMAP.md` é lista de desejos revisável. Único traço "planejado": metas por versão major. | +| **RUP** | **Baixa** | Sem fases formais (concepção/elaboração/construção/transição) nem artefatos UML mantidos; porém há **desenvolvimento iterativo** e foco em arquitetura (`rlgl`, platforms) lembrando o princípio de "arquitetura primeiro". | +| **Modelo Spotify** | **Nula** | Sem squads/tribos; um mantenedor principal e contribuidores voluntários. As tags de módulo (`[rcore]`, `[rtext]`) lembram áreas de responsabilidade, mas sem times fixos. | + +**Conclusão:** o processo real é um **incremental/ágil informal centrado em um mantenedor**, com forte reuso, CI de *build*/análise estática e *smoke tests* de exemplos, mas **sem testes automatizados das funções da biblioteca** — +o que torna a verificação de regressões em funções puras dependente de revisão humana e de relatos de usuários. diff --git a/trabalho-raylib/03-requisitos/03-requisitos.md b/trabalho-raylib/03-requisitos/03-requisitos.md new file mode 100644 index 000000000000..afb370282e49 --- /dev/null +++ b/trabalho-raylib/03-requisitos/03-requisitos.md @@ -0,0 +1,125 @@ +# 3 — Requisitos reconstruídos do raylib + +Os requisitos abaixo foram **reconstruídos a partir de artefatos reais** (código, configuração, README, CI). Cada um traz evidência rastreável. +Convenção: `[L]` arquivo local, `[GH]` GitHub, `[M]` medido/executado por nós. + +## Requisitos funcionais (RF) + +| ID | Requisito | Evidência | +|---|---|---| +| **RF01** | O sistema deve permitir **criar uma janela e executar o laço de renderização por quadro** (`InitWindow` → laço com `BeginDrawing`/`EndDrawing` → `CloseWindow`), consultando `WindowShouldClose`. | `[L]` `src/rcore.c:586` (`InitWindow`), `:863` (`BeginDrawing`), `:880` (`EndDrawing`), `:726` (`CloseWindow`); `src/platforms/rcore_desktop_glfw.c:173` (`WindowShouldClose`); exemplo `README.md:70-89`; `examples/core/core_basic_window.c` | +| **RF02** | O sistema deve **ler entradas do usuário** — teclado, mouse, gamepad e toque — e expor consultas de estado por quadro (ex.: pressionou *neste* quadro vs. mantido pressionado). | `[L]` estado em `CORE.Input.*` (`src/rcore.c:324-383`); `IsKeyPressed` (`:3882`: compara `previousKeyState`×`currentKeyState`), `IsKeyDown` (`:3908`), `IsGamepadButtonPressed` (`:4025`), `IsMouseButtonPressed` (`:4117`); `PollInputEvents` (`rcore_desktop_glfw.c:1291`) | +| **RF03** | O sistema deve **carregar imagens (CPU) e texturas (GPU) e desenhar texturas, formas e texto**. | `[L]` `LoadImage` (`src/rtextures.c:273`), `LoadTexture` (`:4467`), `DrawTexture` (`:4841`), `DrawText` (`src/rtext.c:1211`); structs `Image`/`Texture`/`Font` (`src/raylib.h:264-324`) | +| **RF04** | O sistema deve **carregar e reproduzir áudio** (efeitos curtos e música em *streaming*). | `[L]` `InitAudioDevice` (`src/raudio.c:465`), `LoadSound` (`:937`), `PlaySound` (`:1200`), `LoadMusicStream` (`:1355`), `UpdateMusicStream` (`:1900`); formatos no `README.md:50` | +| **RF05** | O sistema deve oferecer **utilitários de arquivo/texto/hash independentes de janela** (extensão e nome de arquivo, caminhos absolutos, UTF-8, Base64, CRC32/MD5/SHA-1/SHA-256). *(Base da evolução proposta.)* | `[L]` `GetFileExtension` (`src/rcore.c:2500`), `GetFileName` (`:2522`), `IsPathAbsolute` (`:2889`), `ComputeCRC32` (`:3235`), `ComputeMD5` (`:3281`), `ComputeSHA1` (`:3399`), `ComputeSHA256` (`:3509`), `EncodeDataBase64` (`:3111`); `GetCodepoint` (`src/rtext.c:2437`) | + +## Requisitos não funcionais (RNF) + +| ID | Categoria | Requisito | Evidência | +|---|---|---|---| +| **RNF01** | **Portabilidade** | A biblioteca deve compilar e funcionar em várias plataformas/back-ends (Windows, Linux, macOS, Web, Android, DRM/Raspberry Pi, *memory*), escolhidos em tempo de compilação. | `[L]` lista de plataformas `src/rcore.c:6-35`; seleção por macro `:518-533`; 10 arquivos em `src/platforms/`; workflows `build_windows/linux/macos/android/webassembly.yml` | +| **RNF02** | **Simplicidade / aprendizagem** | A API deve ser pequena e legível para iniciantes, **sem dependências externas** para o usuário; funções são "mini-tutoriais". | `[L]` `README.md:37` ("NO external dependencies"), `CONTRIBUTING.md:18-19`, `CONVENTIONS.md` (nomes `TitleCase`, comentários antes da linha); exemplo mínimo de 5 chamadas | +| **RNF03** | **Desempenho** | O desenho deve ser agrupado em lotes (*batching*) para reduzir chamadas de desenho, e o tempo por quadro deve ser controlável (FPS alvo). | `[L]` `rlRenderBatch`/`rlDrawCall` (`src/rlgl.h:407-428`); `RL_DEFAULT_BATCH_BUFFER_ELEMENTS 8192` (`:207`); `EndDrawing` → `rlDrawRenderBatchActive` (`src/rcore.c:882`); `SetTargetFPS` (`:1576`); espera parcialmente ocupada (`src/config.h:93-95`) | +| **RNF04** | **Configurabilidade / tamanho** | Módulos e recursos devem poder ser ligados/desligados na compilação para reduzir tamanho e adaptar a sistemas embarcados. | `[L]` `SUPPORT_MODULE_RSHAPES/RTEXTURES/RTEXT/RMODELS/RAUDIO` (`src/config.h:40-53`) e dezenas de `SUPPORT_*`; log dos módulos carregados em `InitWindow` (`src/rcore.c:612-639`) | +| **RNF05** | **Segurança / robustez** | Entradas externas (URLs, arquivos de eventos, caminhos) devem ser validadas; o código passa por análise estática periódica. | `[L]` CHANGELOG 6.2: auditoria ROS (`CHANGELOG:13`), `OpenURL()` `CLN-002` (`:31`), automação `CLN-005/006` (`:32`); `analyze_codeql.yml` com `cron: '0 0 * * 1'` (semanal); `clang_tidy.yml` | +| **RNF06** | **Licenciamento** | O projeto deve permitir uso comercial e distribuição, mantendo o aviso de copyright. | `[L]` `LICENSE` (zlib/libpng), `README.md:160` | + +> Nota crítica: os RNF acima são verificados por **build (CI), análise estática e *smoke test* dos exemplos** (`tools/rexm`), mas **nenhum é coberto por testes +> automatizados das funções da biblioteca** (não há `add_test()` no repositório) `[L]`. Este é o elo com a evolução proposta (RNF07 abaixo). + +### Requisito não funcional proposto pela evolução + +| ID | Categoria | Requisito | Evidência de necessidade | +|---|---|---|---| +| **RNF07** | **Testabilidade / manutenibilidade** | As funções puras do núcleo (arquivo, texto, hash, codificação) devem ter testes de regressão **executáveis sem janela/GPU** em um comando e no CI. | Sem testes de funções no repo: `enable_testing()` existe (`CMakeLists.txt:57`, `src/CMakeLists.txt:194`) e o CI roda `ctest` (`build_cmake.yml:67,111`), mas **não há nenhum `add_test()`** `[L]`; bugs: #6143/#6144 (SHA-256), PRs #6312 e #6326 (`GetFileExtension`), #6348 (`GetCodepoint`) `[GH]` | + +## Histórias de usuário + +- **US01 e US02** mostram o que o raylib **já faz** (dá para conferir no código). +- **US03, US04 e US05** mostram o que a **nossa evolução** entrega (os testes automáticos). + +### US01 — Primeira janela (Persona 1: estudante) · existente + +**Como** estudante iniciante, **quero** abrir uma janela e escrever um texto nela com poucas linhas de código, **para** ver o resultado já na primeira aula, sem instalar nada a mais. + +- **Cenário 1.1 — Funciona**\ + **Dado que** a biblioteca raylib já está pronta e ligada ao meu programa,\ + **Quando** eu chamo `InitWindow(800, 450, "…")` e, dentro de um laço `while (!WindowShouldClose())`, desenho o texto com `DrawText(...)` entre `BeginDrawing()` e `EndDrawing()`,\ + **Então** aparece uma janela de 800×450 com o texto, e o laço termina quando eu fecho a janela ou aperto ESC (`exitKey = KEY_ESCAPE`, `rcore.c:650`). +- **Cenário 1.2 — Fechar direito**\ + **Dado que** a janela está aberta,\ + **Quando** eu chamo `CloseWindow()`,\ + **Então** o raylib fecha a janela e limpa o estado interno (`CORE`), e eu posso abrir outra janela depois (`rcore.c:736-740`). +- **Cenário 1.3 — Falha ao iniciar** *(ligado à issue #6351, que está aberta)*\ + **Dado que** o computador não tem tela disponível,\ + **Quando** `InitWindow()` não consegue iniciar (`InitPlatform() != 0`),\ + **Então** ele escreve o aviso "Failed to initialize platform" e termina (`rcore.c:659-663`). Mas, segundo a issue #6351 `[GH]`, chamar `CloseWindow()` depois disso ainda trava o programa. + +### US02 — Reagir a uma tecla (Persona 2: desenvolvedor de protótipos e aplicações gráficas) · existente + +**Como** desenvolvedor de protótipos, **quero** saber que uma tecla foi apertada *neste exato quadro*, **para** fazer uma ação (pular, atirar) uma vez só por toque, e não várias vezes enquanto o dedo fica na tecla. + +- **Cenário 2.1 — Apertar a tecla**\ + **Dado que** a tecla `SPACE` estava solta no quadro anterior,\ + **Quando** ela está apertada no quadro atual,\ + **Então** `IsKeyPressed(KEY_SPACE)` responde `true` (estava solta e agora está apertada: `rcore.c:3888`). +- **Cenário 2.2 — Segurar a tecla**\ + **Dado que** `SPACE` já estava apertada no quadro anterior,\ + **Quando** eu continuo segurando,\ + **Então** `IsKeyPressed(KEY_SPACE)` responde `false`, e `IsKeyDown(KEY_SPACE)` responde `true` (a tecla continua apertada). +- **Cenário 2.3 — Tecla inválida**\ + **Dado que** eu passo um número de tecla inválido (`0`, ou maior ou igual a `MAX_KEYBOARD_KEYS`, que é 512),\ + **Quando** eu chamo `IsKeyPressed(key)`,\ + **Então** ele responde `false`, sem dar erro nem travar (`rcore.c:3886`). + +### US03 — Rodar os testes com um comando (Persona 3: contribuidor) · evolução + +**Como** contribuidor, **quero** rodar todos os testes com um único comando, **para** saber em poucos segundos se minha mudança estragou alguma função, antes de abrir o PR. + +- **Cenário 3.1 — Tudo certo**\ + **Dado que** eu já compilei a biblioteca (`libraylib.a`) e estou na pasta `tests/`,\ + **Quando** eu rodo `make test`,\ + **Então** os 3 programas de teste rodam, o resumo mostra `0 failed` e o comando termina com sucesso `[M]` (65 + 29 + 26 = 120 verificações). +- **Cenário 3.2 — Um erro é pego**\ + **Dado que** alguém estraga o cálculo de `ComputeSHA256()` (um erro de preenchimento, o "padding"),\ + **Quando** eu rodo `make test`,\ + **Então** o `test_hash` falha nos tamanhos 56, 57, 59, 120 e 121, e o `make` termina com erro `[M]` (foi o teste de mutação, ver `06-implementacao/`). + +### US04 — Bug conhecido não deixa tudo vermelho (Persona 3 / mantenedor) · evolução + +**Como** mantenedor, **quero** anotar no teste que um bug já é conhecido (com o número do PR ou da issue), **para** deixar o problema registrado sem pintar o CI de vermelho enquanto a correção não chega. + +- **Cenário 4.1 — Falha esperada (XFAIL)**\ + **Dado que** o PR #6348 (que corrige o tamanho devolvido por `GetCodepoint` em texto cortado) ainda estava aberto (situação em 01–02/11/2026),\ + **Quando** eu rodo `test_utf8`,\ + **Então** apareciam 3 linhas `XFAIL … (known bug PR #6348)` e o programa terminava com sucesso `[M]`. +- **Cenário 4.2 — A correção chega (XPASS)**\ + **Dado que** o PR #6348 foi aceito (mesclado em 09/11/2026, commit `7e626d65`) `[GH]` e o bug não existe mais,\ + **Quando** eu rodo `test_utf8`,\ + **Então** as linhas passam a mostrar `XPASS … seems FIXED`, avisando que aquela verificação já pode virar um teste normal (`CHECK`), como o `rtest.h` foi feito para fazer. **Foi o que aconteceu** ao atualizar o fork para o `master` de 10/11/2026: as 3 linhas viraram `XPASS` e a verificação foi promovida a `CHECK` `[M]`. + +### US05 — Fixar o comportamento de uma função (Persona 4: autor de binding) · evolução + +**Como** autor de binding (quem adapta o raylib para outra linguagem), **quero** que o comportamento de funções como `GetFileExtension()` fique gravado em testes, **para** não ser pego de surpresa se ele mudar numa versão futura. + +- **Cenário 5.1 — Arquivo oculto**\ + **Dado que** o arquivo se chama `.gitignore` (ou `projeto/.gitignore`),\ + **Quando** eu chamo `GetFileExtension(...)`,\ + **Então** ele devolve `NULL` (nenhuma extensão), e não `.gitignore`. Essa regra foi corrigida no PR #6326 `[M]`. +- **Cenário 5.2 — Ponto só no nome da pasta**\ + **Dado que** o caminho é `my.dir/README`,\ + **Quando** eu chamo `GetFileExtension(...)`,\ + **Então** ele devolve `NULL`, porque o ponto está no nome da pasta e não no do arquivo. Essa regra foi corrigida no PR #6312 `[M]`. +- **Cenário 5.3 — Extensão normal**\ + **Dado que** o caminho é `archive.tar.gz`,\ + **Quando** eu chamo `GetFileExtension(...)`,\ + **Então** ele devolve `.gz` (só a última extensão). + +## Rastreabilidade história → teste + +| História/cenário | Teste automatizado (pasta `06-implementacao/tests/`) | +|---|---| +| US03/3.1, 3.2 | `Makefile` (`make test`), `test_hash.c::test_sha256_boundaries` | +| US04/4.1 | `test_utf8.c::test_invalid_size_stays_inside_string` (era `KNOWN_BUG`; hoje é `CHECK`, desde o merge do #6348) | +| US05/5.1–5.3 | `test_paths.c::test_get_file_extension` | +| US01, US02 | **Não cobertos** pela evolução (exigem janela/entrada); permanecem fora do MVP — ver `05-evolucao/` | diff --git a/trabalho-raylib/04-uml/04-uml.md b/trabalho-raylib/04-uml/04-uml.md new file mode 100644 index 000000000000..e295355fa40e --- /dev/null +++ b/trabalho-raylib/04-uml/04-uml.md @@ -0,0 +1,404 @@ +# 4 — UML e compreensão do sistema + +## 4.1 Diagrama de contexto + +Mostra o raylib como caixa-preta, seus usuários e os sistemas externos com os quais interage. + +```mermaid +flowchart LR + dev(["Desenvolvedor / estudante
(escreve jogos em C)"]) + bind(["Autor de binding
(+70 linguagens)"]) + contrib(["Contribuidor / mantenedor"]) + + subgraph SYS["raylib — biblioteca C (zlib)"] + api["API pública
raylib.h"] + end + + os["Sistema de janelas e SO
Win32 · X11/Wayland · Cocoa · Android · DRM · Web"] + gpu["GPU / driver gráfico
OpenGL 1.1–4.3, ES 2/3
ou renderizador por software"] + aud["Dispositivo de áudio"] + fs["Sistema de arquivos
(imagens, fontes, modelos, sons)"] + ext["Bibliotecas embutidas
stb · miniaudio · cgltf · GLFW · glad"] + gh["GitHub
Issues · PRs · Actions (CI)"] + + dev -->|"chama funções C"| api + bind -->|"encapsula a API"| api + contrib -->|"abre issues/PRs"| gh + gh -->|"build + clang-tidy + CodeQL"| SYS + SYS -->|"cria janela, lê entradas"| os + SYS -->|"envia lotes de vértices/texturas"| gpu + SYS -->|"reproduz amostras"| aud + SYS -->|"lê/grava arquivos"| fs + SYS -.->|"compila junto (sem dependência externa)"| ext +``` + +--- + +## 4.2 Diagrama de classes + +Recorte das **estruturas de dados centrais**: estado global do núcleo, recursos gráficos/modelos/áudio e o lote de renderização do `rlgl`. + +```mermaid +classDiagram + direction LR + + class CoreData { + <> + +Window + +Storage + +Input + +Time + } + class Window { + <> + +title + +flags + +ready + +shouldClose + +screen / render / display : Size + +position : Point + +screenScale : Matrix + } + class Input { + <> + } + class Keyboard { + <> + +exitKey + +currentKeyState[512] + +previousKeyState[512] + +keyPressedQueue[16] + } + class Mouse { + <> + +currentPosition + +previousPosition + +currentButtonState[8] + } + class Gamepad { + <> + +ready[4] + +axisState[4][8] + } + class Touch { + <> + +pointCount + +position[8] + } + class Time { + <> + +current / previous + +update / draw / frame + +target + +frameCounter + } + CoreData *-- Window + CoreData *-- Input + CoreData *-- Time + Input *-- Keyboard + Input *-- Mouse + Input *-- Gamepad + Input *-- Touch + + class Image { + <> + +data + +width + +height + +mipmaps + +format + } + class Texture { + <> + +id + +width + +height + +mipmaps + +format + } + class RenderTexture { + <> + +id : fbo + +texture : Texture + +depth : Texture + } + class GlyphInfo { + <> + +value : unicode + +offsetX / offsetY + +advanceX + +image : Image + } + class Font { + <> + +baseSize + +glyphCount + +texture : Texture + +recs[] + +glyphs[] + } + Texture ..> Image : LoadTextureFromImage + RenderTexture *-- Texture + Font *-- Texture + Font o-- "*" GlyphInfo + GlyphInfo *-- Image + + class Shader { + <> + +id + +locs[] + } + class MaterialMap { + <> + +texture : Texture + +color + +value + } + class Material { + <> + +shader : Shader + +maps[] + +params[4] + } + class Mesh { + <> + +vertexCount + +triangleCount + +vertices / texcoords / normals + +vaoId + +vboId[] + } + class Model { + <> + +transform : Matrix + +meshCount + +materialCount + +meshes[] + +materials[] + +skeleton + } + Model o-- "*" Mesh + Model o-- "*" Material + Material *-- Shader + Material o-- "*" MaterialMap + MaterialMap *-- Texture + + class AudioStream { + <> + +buffer : rAudioBuffer* + +sampleRate + +sampleSize + +channels + } + class Sound { + <> + +stream : AudioStream + +frameCount + } + class Music { + <> + +stream : AudioStream + +looping + +ctxType / ctxData + } + Sound *-- AudioStream + Music *-- AudioStream + + class rlRenderBatch { + <> + +bufferCount + +currentBuffer + +drawCounter + +currentDepth + } + class rlVertexBuffer { + <> + +elementCount + +vertices / texcoords / colors + +vaoId + +vboId[5] + } + class rlDrawCall { + <> + +mode + +vertexCount + +textureId + } + rlRenderBatch o-- "*" rlVertexBuffer + rlRenderBatch o-- "*" rlDrawCall +``` + +--- + +## 4.3 Diagrama de pacotes + +Módulos de `src/` e dependências por `#include`. Subgrafos representam **pacotes**; setas = "usa/inclui". +O `rcore.c` escolhe **um** back-end de plataforma por macro (`PLATFORM_*`). + +```mermaid +flowchart TB + subgraph PUB["«package» API pública"] + raylibh["raylib.h"] + cfg["config.h
(flags SUPPORT_*)"] + end + + subgraph CORE["«package» núcleo"] + rcore["rcore.c
janela · entrada · tempo · arquivos · hash"] + subgraph PLAT["«package» platforms/ (1 por build)"] + glfwp["rcore_desktop_glfw.c"] + sdlp["rcore_desktop_sdl.c"] + rgfwp["rcore_desktop_rgfw.c"] + winp["rcore_desktop_win32.c"] + webp["rcore_web*.c"] + drmp["rcore_drm.c"] + andp["rcore_android.c"] + memp["rcore_memory.c"] + end + end + + subgraph MODS["«package» módulos opcionais (SUPPORT_MODULE_*)"] + rshapes["rshapes.c"] + rtextures["rtextures.c"] + rtext["rtext.c"] + rmodels["rmodels.c"] + raudio["raudio.c"] + end + + subgraph HDR["«package» cabeçalhos internos reutilizáveis"] + rlgl["rlgl.h
abstração OpenGL"] + raymath["raymath.h"] + rcamera["rcamera.h"] + rgestures["rgestures.h"] + end + + subgraph EXT["«package» external/ (embutido)"] + glfw["GLFW (via rglfw.c)"] + glad["glad.h"] + rlsw["rlsw.h
renderizador por software"] + stb["stb_image · stb_truetype
stb_rect_pack · stb_image_write"] + loaders["cgltf · tinyobj · m3d
par_shapes · vox_loader"] + audlibs["miniaudio · dr_wav/mp3/flac
stb_vorbis · qoa · jar_xm/mod"] + end + + rcore --> raylibh + rcore --> cfg + rcore --> rlgl + rcore --> raymath + rcore --> rcamera + rcore --> rgestures + rcore -->|"#include por macro"| PLAT + glfwp --> glfw + rshapes --> rlgl + rtextures --> rlgl + rtextures --> stb + rtext --> rlgl + rtext --> stb + rmodels --> rlgl + rmodels --> raymath + rmodels --> loaders + raudio --> audlibs + rlgl --> glad + rlgl -->|"GRAPHICS_API_OPENGL_SOFTWARE"| rlsw + rshapes --> raylibh + rtextures --> raylibh + rtext --> raylibh + rmodels --> raylibh + raudio --> raylibh +``` + +--- + +## 4.4 Diagrama de atividades — um quadro do laço de renderização + +Fluxo de `BeginDrawing()` → desenho do usuário → `EndDrawing()` (com `SUPPORT_CUSTOM_FRAME_CONTROL = 0`, o padrão). + +```mermaid +flowchart TD + start(("início do quadro")) --> bd["BeginDrawing():
mede tempo de update,
zera matriz modelview,
aplica screenScale"] + bd --> user["Código do usuário:
DrawText / DrawTexture / DrawRectangle…
(vértices vão para o lote rlgl)"] + user --> ed["EndDrawing(): rlDrawRenderBatchActive()
envia o lote à GPU"] + ed --> rec{"gravando
automation events?"} + rec -->|sim| rae["RecordAutomationEvent()"] + rec -->|não| swap + rae --> swap["SwapScreenBuffer()
(back buffer → tela)"] + swap --> t1["calcula tempo de draw e
frame = update + draw"] + t1 --> wait{"frame < target
(SetTargetFPS)?"} + wait -->|sim| wt["WaitTime(target − frame)
soma espera ao frame"] + wait -->|não| poll + wt --> poll["PollInputEvents():
lê teclado/mouse/gamepad/janela"] + poll --> f12{"F12 pressionada e
SUPPORT_SCREEN_CAPTURE?"} + f12 -->|sim| shot["TakeScreenshot(screenshotNNN.png)"] + f12 -->|não| cnt + shot --> cnt["frameCounter++"] + cnt --> close{"WindowShouldClose()?"} + close -->|não| start + close -->|sim| fin(("fim do laço → CloseWindow()")) +``` + +--- + +## 4.5 Diagrama de sequência — inicialização da janela e primeiro quadro (back-end GLFW) + +```mermaid +sequenceDiagram + autonumber + actor U as Programa do usuário + participant C as rcore.c + participant P as rcore_desktop_glfw.c
(InitPlatform) + participant G as GLFW + participant L as rlgl.h + participant T as rtext.c / rshapes.c / rtextures.c + + U->>C: InitWindow(800, 450, "título") + C->>C: inicializa CORE.Window / CORE.Input (exitKey = ESC) + C->>P: InitPlatform() + P->>G: glfwInit() + P->>G: glfwCreateWindow(...) + P->>G: glfwMakeContextCurrent() + P->>L: rlLoadExtensions(glfwGetProcAddress) + P->>G: glfwSetKeyCallback / glfwSetFramebufferSizeCallback + P->>C: InitTimer() + P-->>C: 0 (sucesso) + C->>L: rlglInit(render.width, render.height) + C->>L: SetupViewport() + C->>T: LoadFontDefault() + SetShapesTexture() + C->>C: SetRandomSeed(time(NULL)) + C-->>U: retorna (janela pronta) + + loop enquanto !WindowShouldClose() + U->>C: BeginDrawing() + U->>T: DrawText(...) / DrawRectangle(...) + T->>L: rlBegin / rlVertex / rlEnd (acumula no lote, texto passa por DrawTexturePro) + U->>C: EndDrawing() + C->>L: rlDrawRenderBatchActive() + C->>P: SwapScreenBuffer() + P->>G: glfwSwapBuffers() + C->>P: PollInputEvents() + P->>G: glfwPollEvents() + end + + U->>C: CloseWindow() + C->>L: rlglClose() + C->>P: ClosePlatform() + P->>G: glfwDestroyWindow() / glfwTerminate() +``` + +--- + +## Correspondências entre diagramas e código + +| # | Elemento do diagrama | Elemento concreto no código | +|---|---|---| +| 1 | Classe `CoreData` (e `Window`, `Input`, `Keyboard`, `Time`…) — 5.2 | `typedef struct CoreData` em `src/rcore.c:298-395`; instância global `CoreData CORE` em `src/rcore.c:402` | +| 2 | Classes `Image`, `Texture`, `RenderTexture`, `Font`, `GlyphInfo` — 5.2 | `src/raylib.h:264`, `:273`, `:288`, `:317`, `:308` | +| 3 | `Model o-- Mesh/Material`, `Material o-- MaterialMap` — 5.2 | `Model` em `src/raylib.h:418` (`Mesh *meshes`, `Material *materials`); `Material` em `:388` (`MaterialMap *maps`) | +| 4 | `rlRenderBatch`, `rlVertexBuffer`, `rlDrawCall` — 5.2 | `src/rlgl.h:420`, `:386`, `:407`; limites `RL_DEFAULT_BATCH_*` em `:203-220` | +| 5 | Pacote `platforms/` com 1 back-end por build — 5.3 | `#if defined(PLATFORM_DESKTOP_GLFW) … #include "platforms/rcore_desktop_glfw.c"` em `src/rcore.c:518-533`; 10 arquivos em `src/platforms/` | +| 6 | Dependência `rlgl → rlsw` (renderizador por software) — 5.3 | `#include "external/rlsw.h"` em `src/rlgl.h:850` | +| 7 | Pacote `external/` com GLFW embutido — 5.3 | `src/rglfw.c:85-182` inclui os `.c` do GLFW por plataforma | +| 8 | Atividade `BeginDrawing`/`EndDrawing`, `WaitTime`, `PollInputEvents`, F12 — 5.4 | `src/rcore.c:863-922` (`BeginDrawing` 863, `EndDrawing` 880); `WaitTime` em `:1652`; `PollInputEvents` em `rcore_desktop_glfw.c:1291` | +| 9 | Sequência `InitWindow → InitPlatform → rlglInit → LoadFontDefault` — 5.5 | `src/rcore.c:586-723` (`InitPlatform` em `:657`, `rlglInit` em `:678`, `LoadFontDefault` em `:686`) | +| 10 | Mensagens `glfwInit`, `glfwCreateWindow`, `rlLoadExtensions`, `InitTimer` — 5.5 | `src/platforms/rcore_desktop_glfw.c:1489`, `:1670/1698`, `:1856`, `:1897` | +| 11 | `CloseWindow → rlglClose → ClosePlatform` e `CORE = {0}` — 5.5 | `src/rcore.c:726-743`; `ClosePlatform` em `rcore_desktop_glfw.c:1927-1930` | + + diff --git a/trabalho-raylib/05-evolucao/05-evolucao.md b/trabalho-raylib/05-evolucao/05-evolucao.md new file mode 100644 index 000000000000..42679d968367 --- /dev/null +++ b/trabalho-raylib/05-evolucao/05-evolucao.md @@ -0,0 +1,58 @@ +# 5 — A evolução proposta: testes de regressão headless para o núcleo utilitário + +## 5.1 Proposta + +| Campo | Conteúdo | +|---|---| +| **Problema** | O raylib **não possui testes automatizados das funções da biblioteca**. As verificações existentes são: build no CI, análise estática (clang-tidy, CodeQL), *smoke test* dos exemplos (`tools/rexm`) e testes manuais da comunidade (#5664) — todas verificam "compila/inicializa/fecha", **não se o resultado de uma função está correto**. O exigido de um PR é "o build não quebra" (`CONTRIBUTING.md:63-64`). Funções puras e simples — hash, caminhos, UTF-8 — regridem e são corrigidas só depois que um usuário reporta. | +| **Usuário afetado** | **Persona 3** (contribuidor/mantenedor): sem rede de segurança, cada PR depende de revisão humana. **Persona 4** (autor de binding): comportamento que muda entre versões sem ser fixado por teste. **Persona 1/2** (usuários finais): recebem funções com bug. | +| **Evidência** | (1) **"Gancho" de testes vazio**: `enable_testing()` em `CMakeLists.txt:57` e `src/CMakeLists.txt:194`; o CI executa `ctest` em `build_cmake.yml:67` e `:111`; porém **nenhum `add_test()`** existe em `.txt/.cmake/.zig/.yml` (fora de `src/external`) nem há pasta/arquivo de testes `[L]` (busca refeita após uma primeira busca incompleta — ver `08-ia/ia.md`). Os demais workflows só compilam/analisam. (2) **`ComputeSHA256()` errada** para tamanhos `mod 64 ∈ 56..59`: issue **#6143** + PR **#6144** (12/09/2026), registrado no CHANGELOG 6.2 com `-WARNING-` `[GH][L]`. (3) **`GetFileExtension()` corrigida duas vezes em 3 dias**: PRs **#6312** (21/10) e **#6326** (24/10/2026) `[GH]`. (4) **`GetCodepoint()` com tamanho inválido** lendo além do fim da string: PR **#6348** (aberto em 30/10/2026; mesclado em 09/11/2026, commit `7e626d65`) `[GH]`. (5) Outros ajustes de funções utilitárias do núcleo no CHANGELOG 6.2: `GetPrevDirectoryPath()` (#6073), `FileText*()` (#6210), `IsPathAbsolute()` (remoção de `isalpha()`), `GetFPS()` (#6265) `[L]`. (6) O próprio `rcore.c` declara `SUPPORT_AUTOMATION_EVENTS` "useful for automated testing systems" (`rcore.c:62-63`), mas isso é para jogos, não para a biblioteca. | +| **Solução proposta** | Suíte de testes em `tests/` na raiz do repositório: (a) *mini-helper* `rtest.h` (C99, sem dependências, em linha com a filosofia "sem dependências externas"), (b) testes **headless** — não criam janela nem contexto OpenGL — das funções puras de `rcore.c` e `rtext.c`, (c) `Makefile` com `make test`, (d) workflow de CI que roda a suíte, (e) mecanismo `KNOWN_BUG` (XFAIL) para registrar bugs conhecidos com o número da issue/PR. | +| **Benefício esperado** | Detectar regressões antes do merge; documentar o comportamento esperado de cada função (os testes funcionam como especificação executável); reduzir a carga da revisão humana; facilitar PRs pequenos de novos contribuidores; dar a autores de *bindings* um contrato verificável. | +| **Prioridade** | **Alta (Should-have, MoSCoW).** Justificativa: custo baixo, risco baixo (não altera `src/`), retorno contínuo, e destrava correções seguras nos back-ends. Não é *Must* porque a biblioteca funciona sem isso há 13 anos. | + +### Achados novos feitos ao escrever os testes `[M]` + +1. **`GetCodepoint()` apresentava o problema do PR #6348 no `master` de 31/10 (corrigido depois, em 09/11):** para `"\xC3"`, `"\xE2\x82"` e `"\xF0\x9F\x98"` (sequências truncadas) o tamanho devolvido excede `strlen`, então `texto += tamanho` passaria do `'\0'`. Foi registrado como `XFAIL` (3 ocorrências); ao atualizar o fork em 10/11, os 3 viraram `XPASS` e foram promovidos a `CHECK` (teste de regressão). +2. **`GetFileExtension(NULL)` provoca violação de acesso** (código de saída `0xC0000005` no Windows): `GetFileName(NULL)` devolve `NULL` (`rcore.c:2522-2531`) e em seguida `strrchr(NULL, '.')` é chamado (`rcore.c:2503-2504`). Já `GetFileName(NULL)` e `IsPathAbsolute(NULL)` tratam `NULL` com segurança. Em busca na API do GitHub **não encontramos** issue sobre isso (busca por "GetFileExtension NULL"; não é prova de inexistência). *Não incluímos como teste automático* porque derrubaria o processo; é candidato a issue/PR futuro — **verifiquem antes de reportar**. + +## 5.2 MVP + +**O que será desenvolvido** + +- `tests/rtest.h` — helper mínimo: `CHECK`, `CHECK_INT`, `CHECK_STR`, `KNOWN_BUG` (XFAIL/XPASS), `RUN`, `RTEST_SUMMARY` (código de saída ≠ 0 em falha). +- `tests/test_hash.c` — `ComputeSHA256/SHA1/MD5` em **14 comprimentos** (0, 1, 3, 55, 56, 57, 59, 60, 63, 64, 65, 119, 120, 121) com **oráculo independente** (.NET), `ComputeCRC32` (valor de verificação padrão `0xCBF43926`) e Base64 (vetores RFC 4648). **65 verificações.** +- `tests/test_paths.c` — `GetFileName`, `GetFileExtension`, `IsFileExtension`, `GetFileNameWithoutExt`, `IsPathAbsolute` (casos Windows/POSIX). **29 verificações.** +- `tests/test_utf8.c` — `GetCodepoint` (válidos, inválidos, truncados), `GetCodepointCount`, `CodepointToUTF8`; inclui o teste de regressão do PR #6348 (3 entradas truncadas; era `KNOWN_BUG` até o merge). **26 verificações.** +- `tests/Makefile` — `make test` (Windows/MSYS2, Linux, macOS). +- Workflow de CI `run_tests.yml` (cópia em `06-implementacao/ci/`), que compila a biblioteca e roda a suíte. + +**Valor entregue:** um comando (`make test`) diz em segundos se funções críticas continuam corretas; regressões como #6143, #6312 e #6326 passam a ser detectadas automaticamente; bugs conhecidos ficam documentados no código. + +**Fora do MVP (e por quê)** + +| Item | Motivo | +|---|---| +| Testes de renderização/janela/áudio (US01, US02) | Exigem GPU/janela/dispositivo; são frágeis em CI e dependem de back-end. Próxima fase: usar `PLATFORM_MEMORY` + `rlsw` (renderizador por software) para testar sem GPU. | +| Matriz de CI multiplataforma (Windows/macOS/ARM) | Testamos no Windows/MSYS2 (local) e no Linux/Ubuntu (um workflow no GitHub Actions); **macOS e ARM não foram testados** (ver `06-implementacao/`). | +| Integração CMake/`ctest` (`add_test()` + `add_subdirectory(tests)`) | **Próximo passo natural**: o CI já executa `ctest`, então registrar os 3 executáveis acenderia um passo que hoje roda vazio. Ficou fora porque altera `CMakeLists.txt` do projeto e **não temos CMake instalado para verificar** — não afirmamos nada que não executamos. | +| Cobertura de código, *fuzzing*, *sanitizers* | Valiosos (ASan acharia #6348), mas ampliam o escopo; ficam como evolução. | +| Corrigir bugs encontrados (`GetFileExtension(NULL)`; o #6348 já foi corrigido por outro contribuidor) | O MVP **não altera `src/`**; corrigir é outra mudança, com decisão do mantenedor. | +| Cobrir todas as funções de `rcore.c`/`rtext.c` | Priorizamos as com histórico de bugs (hash, caminhos, UTF-8). | + +**Justificativa das escolhas:** (1) alvo *headless* garante execução em qualquer máquina e no CI; (2) helper próprio em C evita dependência (Unity, Check, CMocka), coerente com `README.md:37` e `CONTRIBUTING.md:18-19`; (3) oráculo externo impede "testar o código com ele mesmo"; (4) XFAIL permite entregar sem vermelho no CI e sem esconder o bug; (5) priorizar funções com histórico de regressão maximiza valor por linha de teste. + +## 5.3 Análise de impacto + +| Área | Impacto | Detalhe | +|---|---|---| +| **Classes / structs** | **Nenhum** | Nenhuma `struct` é criada/alterada. Os testes só chamam a API pública declarada em `raylib.h`. | +| **Pacotes / módulos** | **Nenhum em `src/`** (MVP) | Novo diretório de topo `tests/`. Indiretamente relacionados: `rcore.c` (arquivos, hash, Base64) e `rtext.c` (UTF-8). | +| **Componentes** | **Novo componente de teste** | `rtest.h` + 3 executáveis. Linkam com `libraylib.a`. | +| **Banco de dados** | **Não se aplica** | O raylib não usa banco de dados. | +| **APIs** | **Nenhuma alteração** | API pública e ABI inalteradas. *Risco colateral*: fixar comportamento por teste torna futuras mudanças de semântica explícitas (ex.: o `-WARNING-` do CHANGELOG deveria acompanhar atualização de teste). | +| **Interfaces** | **Nenhuma** | Sem interface gráfica; a "interface" nova é `make test` + saída em texto. | +| **Build / CI** | **Novo** | `tests/Makefile`; workflow `.github/workflows/run_tests.yml`. `CMakeLists.txt` e `src/Makefile` **não** são tocados no MVP. Complementa (não substitui) o `rexm test`, que valida exemplos, e o passo `ctest` hoje sem testes. | +| **Testes** | **Principal impacto** | De 0 para 120 verificações automatizadas (3 XFAIL no início, zerados após o merge do #6348). | +| **Documentação** | **Pequeno** | `tests/README` (como rodar/escrever testes); sugerido: um parágrafo em `CONTRIBUTING.md` ("rode `make test` antes de abrir o PR"). | +| **Riscos** | Baixos | (a) Testes dependentes de plataforma (caminhos absolutos: tratados com `#ifdef _WIN32`); (b) `XFAIL` pode envelhecer — mitigado por `XPASS` avisando; (c) aceitação upstream: a filosofia "poucas funções, simples" pode resistir a infraestrutura nova → por isso o PR foi aberto primeiro no **fork da dupla** (revisão interna) e depois enviado ao repositório oficial, onde a aceitação cabe ao mantenedor. **Desfecho (10/11/2026):** o mantenedor fechou o PR #6400 sem mesclar, com o comentário "No, thanks." e sem justificar — o risco (c) se concretizou. | diff --git a/trabalho-raylib/06-implementacao/PR_DESCRIPTION.md b/trabalho-raylib/06-implementacao/PR_DESCRIPTION.md new file mode 100644 index 000000000000..99c581e740f2 --- /dev/null +++ b/trabalho-raylib/06-implementacao/PR_DESCRIPTION.md @@ -0,0 +1,18 @@ +# [tests] Add headless regression tests for core utility functions + + + +raylib has no automated tests for its library functions. Bugs in small pure +functions have reached users before (#6143 SHA-256, #6312/#6326 GetFileExtension, +#6348 GetCodepoint). + +This PR adds headless tests (no window/GPU) for hash/encoding functions, path +helpers and UTF-8 functions, a `make test` target in `tests/`, and a small Linux +CI workflow. No changes in `src/`. + +To run: `cd src && make PLATFORM=PLATFORM_DESKTOP`, then `cd ../tests && make test` +(120 checks pass). Tested on Windows (MSYS2) and Ubuntu (CI), not on macOS. + +Parts of the code were written with AI assistance (Claude Code); we reviewed and ran everything. diff --git a/trabalho-raylib/06-implementacao/README.md b/trabalho-raylib/06-implementacao/README.md new file mode 100644 index 000000000000..d760e2d5d010 --- /dev/null +++ b/trabalho-raylib/06-implementacao/README.md @@ -0,0 +1,99 @@ +# 7 — Implementação experimental: testes de regressão headless + +## O que foi implementado + +| Arquivo | Função | Verificações | +|---|---|---| +| [`tests/rtest.h`](tests/rtest.h) | Mini-helper de testes (`CHECK`, `CHECK_INT`, `CHECK_STR`, `KNOWN_BUG`, `RUN`, `RTEST_SUMMARY`) | — | +| [`tests/test_hash.c`](tests/test_hash.c) | `ComputeSHA256/SHA1/MD5` em 14 comprimentos de fronteira, `ComputeCRC32`, Base64 (RFC 4648) | 65 | +| [`tests/test_paths.c`](tests/test_paths.c) | `GetFileName`, `GetFileExtension`, `IsFileExtension`, `GetFileNameWithoutExt`, `IsPathAbsolute` | 29 | +| [`tests/test_utf8.c`](tests/test_utf8.c) | `GetCodepoint` (válido/inválido/truncado), `GetCodepointCount`, `CodepointToUTF8` + teste de regressão do PR #6348 | 26 | +| [`tests/Makefile`](tests/Makefile) | `make test` (Windows/MSYS2, Linux, macOS) | — | +| [`ci/run_tests.yml`](ci/run_tests.yml) | Workflow de CI para copiar em `.github/workflows/` do fork | **executado no fork**: 1ª execução falhou, 2ª (com `libglfw3-dev`) verde | +| [`PR_DESCRIPTION.md`](PR_DESCRIPTION.md) | Texto do Pull Request | — | +| [`REVISAO.md`](REVISAO.md) | Roteiro/registro da revisão feita pelo outro integrante | **a preencher** | + +**O MVP não altera nenhum arquivo de `src/`.** + +## Como executar + +Pré-requisitos: `gcc`/`clang` e `make` (Windows: MSYS2/UCRT64 → `mingw32-make`). + +```bash +# na raiz do fork do raylib (a pasta tests/ é copiada para lá) +cd src +make PLATFORM=PLATFORM_DESKTOP # gera src/libraylib.a (Windows: mingw32-make ...) +cd ../tests +make test # compila e roda os 3 testes +make clean +``` + +Windows/PowerShell (como foi feito aqui): `$env:PATH = "C:\msys64\ucrt64\bin;C:\msys64\usr\bin;" + $env:PATH` antes de chamar `mingw32-make`. +**Importante no Windows:** a pasta `C:\msys64\usr\bin` precisa estar no PATH porque o `make test` usa o `sh` do MSYS2. Sem ela, a compilação funciona, +mas o `make test` falha com `t foi inesperado neste momento` (o `mingw32-make` cai no cmd, que não entende o `for` do Makefile). Alternativa: usar o terminal "MSYS2 UCRT64". +A variável `RAYLIB_SRC` aponta para a pasta com `raylib.h` e `libraylib.a` (padrão `../src`): +`make RAYLIB_SRC=/caminho/para/src test`. + +### Saída esperada (executada por nós, Windows 11, gcc 14.2.0 MSYS2) + +``` +=== test_hash === +65 checks, 0 failed, 0 known bugs (XFAIL), 0 fixed known bugs (XPASS) +=== test_paths === +29 checks, 0 failed, 0 known bugs (XFAIL), 0 fixed known bugs (XPASS) +=== test_utf8 === + (nenhuma linha XFAIL/XPASS: o PR #6348 já foi mesclado no raylib) +26 checks, 0 failed, 0 known bugs (XFAIL), 0 fixed known bugs (XPASS) +ALL TEST FILES PASSED +``` + +## Evidências de que os testes funcionam (e não só "passam") + +### 1. Teste de mutação — o teste *detecta* um bug + +Reintroduzimos, numa **cópia descartável** do `rcore.c`, um padding errado em `ComputeSHA256()` +(`paddedSize = dataSize + 4` no lugar de `dataSize + sizeof(bitLen)`, `rcore.c:3545`). Resultado: + +``` +sha256 len=56 MISMATCH sha256 len=57 MISMATCH sha256 len=59 MISMATCH +sha256 len=120 MISMATCH sha256 len=121 MISMATCH +65 checks, 5 failed ... exit code 1 +``` + +Os comprimentos 0, 1, 3, 55, 60, 63, 64, 65 e 119 seguiram corretos — coerente com o bug real descrito em #6143 (`56..59 mod 64`). +**Limite honesto:** é uma mutação **nossa**, não o diff histórico do PR #6144; ela imita a classe do defeito. + +### 2. Oráculo independente + +Os valores esperados de SHA-256/SHA-1/MD5 foram gerados com **.NET `System.Security.Cryptography`** (não com o raylib) sobre a mensagem `'a' × N`; +CRC-32 usa o valor de verificação padrão `0xCBF43926` para `"123456789"`; Base64 usa os vetores da RFC 4648 §10. + +### 3. Bug real documentado como `XFAIL` e depois promovido a `CHECK` + +`test_utf8.c` registrou o problema do PR #6348 (aberto na época): para sequências truncadas (`"\xC3"`, `"\xE2\x82"`, `"\xF0\x9F\x98"`), +`GetCodepoint()` devolvia um tamanho maior que `strlen`, e na 1ª execução apareceram 3 `XFAIL`. O PR foi mesclado em 09/11/2026 (commit `7e626d65`); ao atualizar o fork em 10/11 a saída virou 3 `XPASS` — o aviso que o `rtest.h` foi feito para dar — e a verificação foi promovida a `CHECK`. Hoje é um teste de regressão comum (26 verificações, 0 XFAIL). + +### 4. CI no GitHub Actions (prints) + +Pull request no fork (revisão interna): https://github.com/FaMarcolino/raylib/pull/1 + +Pull request ao projeto original (raysan5/raylib), aberto em 10/11/2026: https://github.com/raysan5/raylib/pull/6400 + +**Desfecho do PR ao projeto original (10/11/2026):** o mantenedor (`raysan5`) **fechou o PR sem mesclar**, com o único comentário "No, thanks.", sem apontar o motivo. Antes disso, os workflows do PR ficaram aguardando aprovação de mantenedor e expiraram sem rodar nenhum job ("This workflow run required approval but was not approved before it expired."); por isso a evidência de CI está **no fork**: `Run headless tests` verde (execuções #4, #5 e #6) e build do macOS verde na execução manual #5. O risco de não aceitação já estava previsto em `05-evolucao/` (riscos, item c). A intervenção continua disponível na branch `feat/headless-tests` do fork. + +**1ª execução: falhou** (commit `9657563`). Faltava instalar `libglfw3-dev` no workflow (erro de link `cannot find -lGL`). + +![CI falhou no commit 9657563](evidencias/ci-1-falhou-commit-9657563.png) + +**Os 7 commits do PR #1.** O CI passa de ❌ (`9657563`) para ✅ após o commit `b83e2d3`, que instala `libglfw3-dev`. + +![Commits do PR #1](evidencias/ci-2-commits-do-pr-1.png) + +**CI verde no PR #1** (testes e CodeQL). + +![CI verde no PR #1](evidencias/ci-3-verde-no-pr-1.png) + +> Observação sobre o CI: o `run_tests.yml` reaproveita as dependências do `build_linux.yml` do raylib. Foi executado no fork (aba *Actions*): a **1ª execução falhou** no passo +> "Run tests" (`exit code 2`) com o erro de link `/usr/bin/ld: cannot find -lGL`, porque o workflow não instalava `libglfw3`/`libglfw3-dev` (que trazem as bibliotecas de desenvolvimento do OpenGL); +> após incluí-los (commit `b83e2d3`), a execução ficou **verde**. Note que era falha de **build/link**, não de teste. +> Ou seja: comprovado em **Windows/MSYS2 (local)** e **Linux/Ubuntu (CI)**; macOS não foi testado. Anexem um print da execução verde na apresentação. diff --git a/trabalho-raylib/06-implementacao/REVISAO.md b/trabalho-raylib/06-implementacao/REVISAO.md new file mode 100644 index 000000000000..e8a60f37cacd --- /dev/null +++ b/trabalho-raylib/06-implementacao/REVISAO.md @@ -0,0 +1,49 @@ +# Revisão do Pull Request (feita pelo outro integrante) + +> **Este arquivo é um roteiro + registro a preencher.** O enunciado exige revisão realizada pelo outro integrante; +> nenhum resultado abaixo foi preenchido por nós — só vale depois que a pessoa revisora **executar** os passos. + +- **Autor do PR:** conta GitHub `FaMarcolino` +- **Revisor(a):** conta GitHub `luanpais` (integrante diferente do autor) +- **Link do PR:** https://github.com/raysan5/raylib/pull/6400 (PR ao projeto original, **fechado pelo mantenedor em 10/11/2026 sem mesclar**; o código revisado continua na branch `feat/headless-tests`. PR interno de revisão no fork: https://github.com/FaMarcolino/raylib/pull/1) +- **Data da revisão:** testes e teste de mutação executados em 10/11/2026; parecer publicado em 13/11/2026 no PR #1 do fork (https://github.com/FaMarcolino/raylib/pull/1) + +## Roteiro de revisão + +### A. Ler e entender (sem executar) +- [ ] O PR toca apenas `tests/` e `.github/workflows/run_tests.yml` (nenhum `src/`)? +- [ ] Cada valor esperado em `test_hash.c` tem origem independente do raylib? (conferir comentário no topo e recalcular 2 valores à mão — ver C.) +- [ ] `KNOWN_BUG` (se houver) cita issue/PR real? Abrir #6348 e confirmar que foi mesclado (commit `7e626d65`) e que o teste correspondente hoje é `CHECK`, não `KNOWN_BUG`. +- [ ] O código dos testes segue `CONVENTIONS.md` (4 espaços, sem TAB, comentário antes da linha, `float x.xf`)? + +### B. Executar +```bash +cd src && make PLATFORM=PLATFORM_DESKTOP +cd ../tests && make test +``` +- [x] Saída final `ALL TEST FILES PASSED`. Contagens: `test_hash` 65 · `test_paths` 29 · `test_utf8` 26 (0 falhas, 0 XFAIL, 0 XPASS). Ambiente do revisor: Windows, MSYS2 UCRT64, gcc 16.2.0, GNU Make 4.4.1, em 10/11/2026. + +### C. Conferir um valor por conta própria +PowerShell (SHA-256 de `'a'` × 56 deve ser `b35439a4…6738a`): +```powershell +$b=[byte[]]@(0x61)*56; ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash($b))).Replace('-','').ToLower() +``` +- [ ] Bateu com o esperado em `test_hash.c`? + +### D. Teste de mutação (o teste realmente pega o bug?) +1. Crie uma **cópia** de `src/` (não altere o original). +2. Em `rcore.c`, troque `unsigned long long paddedSize = dataSize + sizeof(bitLen);` por `... = dataSize + 4;` +3. Apague os objetos da cópia (`rm -f *.o libraylib.a`), recompile **gravando a biblioteca dentro da cópia** (`make PLATFORM=PLATFORM_DESKTOP RAYLIB_RELEASE_PATH=.`; sem isso o Makefile grava em `../src/` e sobrescreve a biblioteca **original**) e rode `test_hash` apontando `RAYLIB_SRC` para a cópia. +- [x] `test_hash` falhou nos comprimentos 56, 57, 59, 120 e 121 (`65 checks, 5 failed`; `make` terminou com `Error 1`); 0, 1, 3, 55, 60, 63, 64, 65 e 119 seguiram `ok`. Ao restaurar a biblioteca original, voltou a `ALL TEST FILES PASSED`. + - **Nota honesta:** a 1ª tentativa foi **inválida** — o `make` gravou a biblioteca mutada em `../src/` e os testes linkaram com a cópia original, então passaram. O revisor percebeu, reconstruiu a biblioteca original e refez com `RAYLIB_RELEASE_PATH=.` (o roteiro acima já foi corrigido). + +### E. Pontos de atenção que a revisão deve avaliar +- Testes de caminho absoluto dependem de `#ifdef _WIN32` — ok para Linux/macOS? +- O workflow de CI: abrir a aba *Actions* e conferir se está verde no commit mais recente do PR. (Histórico, com os hashes de antes do rebase de 10/11/2026: a 1ª execução, no commit `9657563`, falhou; a do commit `b83e2d3`, com `libglfw3-dev`, passou.) Revisor: confirmar isso você mesmo(a) na aba *Actions*. +- Algum teste "trava" o processo? (`GetFileExtension(NULL)` **não** deve estar na suíte.) + +## Parecer + +- **Resultado:** **aprovado com ressalvas** +- **Comentários principais** (resumo; o texto completo está no comentário do revisor no PR #1 do fork): confirmou que só `tests/` e `run_tests.yml` mudaram; rodou a suíte no Windows (gcc 16.2.0) e passou; o teste de mutação falhou nos comprimentos 56, 57, 59, 120 e 121, como esperado. Ressalvas: (1) falta o comprimento 58, que está dentro da faixa do bug; (2) a verificação de UTF-8 truncado é fraca, pois só confere que o tamanho não passa do fim da string; (3) os testes de caminho específicos do Windows só rodam localmente (o CI é Linux); (4) o workflow do macOS falhou uma vez de forma intermitente; (5) algumas convenções de estilo não foram seguidas; (6) algumas funções têm poucos casos de teste. `TODO: conferir este resumo com o texto original do comentário.` +- **Mudanças feitas após a revisão (commits):** `TODO` diff --git a/trabalho-raylib/06-implementacao/ci/run_tests.yml b/trabalho-raylib/06-implementacao/ci/run_tests.yml new file mode 100644 index 000000000000..df55dd8e8e6f --- /dev/null +++ b/trabalho-raylib/06-implementacao/ci/run_tests.yml @@ -0,0 +1,42 @@ +name: Run headless tests + +# Runs the headless tests in tests/ on Linux. +# Dependencies mirror the ones used by build_linux.yml of raylib. +# STATUS: 1st run failed (missing libglfw3-dev); fixed in commit b83e2d3. macOS not tested. + +on: + workflow_dispatch: + push: + paths: + - 'src/**' + - 'tests/**' + - '.github/workflows/run_tests.yml' + pull_request: + paths: + - 'src/**' + - 'tests/**' + - '.github/workflows/run_tests.yml' + +permissions: + contents: read + +jobs: + tests: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install dependencies + run: | + sudo apt-get update -qq + sudo apt-get install -y --no-install-recommends libglfw3 libglfw3-dev libx11-dev libxcursor-dev libxrandr-dev libxinerama-dev libxi-dev libxext-dev libxfixes-dev libwayland-dev libxkbcommon-dev + + - name: Build raylib (static) + working-directory: src + run: make PLATFORM=PLATFORM_DESKTOP -j"$(nproc)" + + - name: Run tests + working-directory: tests + run: make test diff --git a/trabalho-raylib/06-implementacao/evidencias/ci-1-falhou-commit-9657563.png b/trabalho-raylib/06-implementacao/evidencias/ci-1-falhou-commit-9657563.png new file mode 100644 index 000000000000..f3e08f60da1f Binary files /dev/null and b/trabalho-raylib/06-implementacao/evidencias/ci-1-falhou-commit-9657563.png differ diff --git a/trabalho-raylib/06-implementacao/evidencias/ci-2-commits-do-pr-1.png b/trabalho-raylib/06-implementacao/evidencias/ci-2-commits-do-pr-1.png new file mode 100644 index 000000000000..1789106fd959 Binary files /dev/null and b/trabalho-raylib/06-implementacao/evidencias/ci-2-commits-do-pr-1.png differ diff --git a/trabalho-raylib/06-implementacao/evidencias/ci-3-verde-no-pr-1.png b/trabalho-raylib/06-implementacao/evidencias/ci-3-verde-no-pr-1.png new file mode 100644 index 000000000000..11faf3134811 Binary files /dev/null and b/trabalho-raylib/06-implementacao/evidencias/ci-3-verde-no-pr-1.png differ diff --git a/trabalho-raylib/06-implementacao/tests/Makefile b/trabalho-raylib/06-implementacao/tests/Makefile new file mode 100644 index 000000000000..b7031bb21b28 --- /dev/null +++ b/trabalho-raylib/06-implementacao/tests/Makefile @@ -0,0 +1,42 @@ +# Headless tests for raylib (no window, no GPU required to RUN them) +# +# USAGE (from the repository root of the raylib fork, after building src/libraylib.a): +# cd src && make PLATFORM=PLATFORM_DESKTOP (mingw32-make on Windows/MSYS2) +# cd ../tests && make test +# +# VARIABLES: +# RAYLIB_SRC folder with raylib.h and libraylib.a (default: ../src) + +RAYLIB_SRC ?= ../src +CC ?= gcc +CFLAGS ?= -std=c99 -Wall -Wextra -Wno-unused-function -I$(RAYLIB_SRC) + +ifeq ($(OS),Windows_NT) + EXE = .exe + LIBS = -L$(RAYLIB_SRC) -lraylib -lopengl32 -lgdi32 -lwinmm +else + EXE = + UNAME_S := $(shell uname -s) + ifeq ($(UNAME_S),Darwin) + LIBS = -L$(RAYLIB_SRC) -lraylib -framework OpenGL -framework Cocoa -framework IOKit -framework CoreVideo + else + LIBS = -L$(RAYLIB_SRC) -lraylib -lGL -lm -lpthread -ldl -lrt -lX11 + endif +endif + +TESTS = test_hash test_paths test_utf8 + +all: $(addsuffix $(EXE),$(TESTS)) + +%$(EXE): %.c rtest.h + $(CC) $(CFLAGS) -o $@ $< $(LIBS) + +# Runs every test binary; stops at the first failing one (non-zero exit code) +test: all + @for t in $(TESTS); do echo "=== $$t ==="; ./$$t$(EXE) || exit 1; done + @echo "ALL TEST FILES PASSED" + +clean: + rm -f $(addsuffix $(EXE),$(TESTS)) + +.PHONY: all test clean diff --git a/trabalho-raylib/06-implementacao/tests/README.md b/trabalho-raylib/06-implementacao/tests/README.md new file mode 100644 index 000000000000..cdf39b6deb02 --- /dev/null +++ b/trabalho-raylib/06-implementacao/tests/README.md @@ -0,0 +1,41 @@ +# tests/ — testes headless do raylib + +Testes de regressão das funções puras de `rcore.c` e `rtext.c`. **Não abrem janela nem contexto OpenGL**; só linkam com `libraylib.a`. + +```bash +cd ../src && make PLATFORM=PLATFORM_DESKTOP # gera libraylib.a (Windows/MSYS2: mingw32-make) +cd ../tests && make test +``` + +## Escrevendo um teste novo + +```c +#include "raylib.h" +#include "rtest.h" + +static void test_minha_funcao(void) +{ + CHECK_STR(".png", GetFileExtension("a/b.png")); // comparação de strings + CHECK_INT(3, GetCodepointCount("a\xC3\xA9b")); // comparação de inteiros + CHECK(IsPathAbsolute("") == false); // condição booleana + + // Bug conhecido e ainda aberto: não deixa o CI vermelho; vira XPASS quando for corrigido + KNOWN_BUG(resultado_correto, "issue/PR #NNNN"); +} + +int main(void) +{ + SetTraceLogLevel(LOG_NONE); + RUN(test_minha_funcao); + return RTEST_SUMMARY(); +} +``` + +Depois adicione o nome do arquivo (sem `.c`) à variável `TESTS` do `Makefile`. + +## Regras + +1. **Headless:** não chame `InitWindow()`, `LoadTexture()` etc. (precisam de GPU). +2. **Valores esperados independentes:** gere-os com outra ferramenta/RFC, não com o próprio raylib. +3. **Um teste que nunca falhou não prova nada:** faça uma mutação no código e confira que o teste falha. +4. **Não teste o que derruba o processo** (ex.: passar `NULL` a função que não trata `NULL`); documente como issue. diff --git a/trabalho-raylib/06-implementacao/tests/rtest.h b/trabalho-raylib/06-implementacao/tests/rtest.h new file mode 100644 index 000000000000..180f43fb44f6 --- /dev/null +++ b/trabalho-raylib/06-implementacao/tests/rtest.h @@ -0,0 +1,64 @@ +/********************************************************************************************** +* +* rtest - Minimal single-header test helper for raylib headless tests +* +* NOTE: raylib has no unit test framework (see 01-discovery), so this helper is intentionally tiny: +* no dependencies, plain C99, same spirit as the rest of the library. +* +* USAGE: +* CHECK(cond) -> fails the current test if cond is false +* CHECK_INT(expected, actual) -> compares two integers, prints both on failure +* CHECK_STR(expected, actual) -> compares two strings (NULL-safe), prints both on failure +* KNOWN_BUG(cond, "issue/PR") -> expected failure (XFAIL) tracked upstream: +* - cond false: reported as XFAIL, does NOT fail the run +* - cond true : reported as XPASS (bug fixed, update the test) +* RTEST_SUMMARY() -> prints totals, returns process exit code (0 = ok) +* +**********************************************************************************************/ + +#ifndef RTEST_H +#define RTEST_H + +#include +#include + +static int rtestChecks = 0; // Total checks executed +static int rtestFailed = 0; // Checks that failed (make the run fail) +static int rtestXfail = 0; // Known bugs still present +static int rtestXpass = 0; // Known bugs that now pass + +#define CHECK(cond) do { \ + rtestChecks++; \ + if (!(cond)) { rtestFailed++; printf(" FAIL %s:%d: %s\n", __FILE__, __LINE__, #cond); } \ +} while (0) + +#define CHECK_INT(expected, actual) do { \ + long long e_ = (long long)(expected), a_ = (long long)(actual); \ + rtestChecks++; \ + if (e_ != a_) { rtestFailed++; printf(" FAIL %s:%d: %s -> expected %lld, got %lld\n", __FILE__, __LINE__, #actual, e_, a_); } \ +} while (0) + +#define CHECK_STR(expected, actual) do { \ + const char *e_ = (expected), *a_ = (actual); \ + rtestChecks++; \ + if (((e_ == NULL) != (a_ == NULL)) || ((e_ != NULL) && (strcmp(e_, a_) != 0))) { \ + rtestFailed++; \ + printf(" FAIL %s:%d: %s -> expected %s%s%s, got %s%s%s\n", __FILE__, __LINE__, #actual, \ + e_ ? "\"" : "", e_ ? e_ : "NULL", e_ ? "\"" : "", a_ ? "\"" : "", a_ ? a_ : "NULL", a_ ? "\"" : ""); \ + } \ +} while (0) + +#define KNOWN_BUG(cond, ref) do { \ + rtestChecks++; \ + if (cond) { rtestXpass++; printf(" XPASS %s:%d: %s (known bug %s seems FIXED, promote to CHECK)\n", __FILE__, __LINE__, #cond, ref); } \ + else { rtestXfail++; printf(" XFAIL %s:%d: %s (known bug %s)\n", __FILE__, __LINE__, #cond, ref); } \ +} while (0) + +#define RUN(test) do { printf("[ RUN ] %s\n", #test); test(); } while (0) + +#define RTEST_SUMMARY() ( \ + printf("\n%d checks, %d failed, %d known bugs (XFAIL), %d fixed known bugs (XPASS)\n", \ + rtestChecks, rtestFailed, rtestXfail, rtestXpass), \ + (rtestFailed == 0) ? 0 : 1 ) + +#endif // RTEST_H diff --git a/trabalho-raylib/06-implementacao/tests/test_hash.c b/trabalho-raylib/06-implementacao/tests/test_hash.c new file mode 100644 index 000000000000..28d5b39a17c5 --- /dev/null +++ b/trabalho-raylib/06-implementacao/tests/test_hash.c @@ -0,0 +1,137 @@ +// Headless tests for the hash/encoding helpers in rcore.c +// (ComputeSHA256, ComputeSHA1, ComputeMD5, ComputeCRC32, EncodeDataBase64, DecodeDataBase64) +// +// Expected values come from an INDEPENDENT oracle (.NET System.Security.Cryptography) over the +// message 'a' repeated N times, so tests do not depend on raylib's own implementation. +// Lengths 55/56/57/59/60/63/64/65/119/120/121 are the padding boundaries of 512-bit blocks, where +// ComputeSHA256 was wrong before raylib 6.2 (issue #6143 / PR #6144: "wrong hash when message length mod 64 is 56..59"). + +#include "raylib.h" +#include "rtest.h" + +#include + +typedef struct { int len; const char *sha256; const char *sha1; const char *md5; } HashVector; + +static const HashVector vectors[] = { + { 0, "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "da39a3ee5e6b4b0d3255bfef95601890afd80709", "d41d8cd98f00b204e9800998ecf8427e" }, + { 1, "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb", "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8", "0cc175b9c0f1b6a831c399e269772661" }, + { 3, "9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0", "7e240de74fb1ed08fa08d38063f6a6a91462a815", "47bce5c74f589f4867dbd57e9ca9f808" }, + { 55, "9f4390f8d30c2dd92ec9f095b65e2b9ae9b0a925a5258e241c9f1e910f734318", "c1c8bbdc22796e28c0e15163d20899b65621d65a", "ef1772b6dff9a122358552954ad0df65" }, + { 56, "b35439a4ac6f0948b6d6f9e3c6af0f5f590ce20f1bde7090ef7970686ec6738a", "c2db330f6083854c99d4b5bfb6e8f29f201be699", "3b0c8ac703f828b04c6c197006d17218" }, + { 57, "f13b2d724659eb3bf47f2dd6af1accc87b81f09f59f2b75e5c0bed6589dfe8c6", "f08f24908d682555111be7ff6f004e78283d989a", "652b906d60af96844ebd21b674f35e93" }, + { 59, "111bb261277afd65f0744b247cd3e47d386d71563d0ed995517807d5ebd4fba3", "dbc8b8f59ff85a2b1448ed873484b14bf0507246", "762fc2665994b217c52c3c2eb7d9f406" }, + { 60, "11ee391211c6256460b6ed375957fadd8061cafbb31daf967db875aebd5aaad4", "13d956033d9af449bfe2c4ef78c17c20469c4bf1", "cc7ed669cf88f201c3297c6a91e1d18d" }, + { 63, "7d3e74a05d7db15bce4ad9ec0658ea98e3f06eeecf16b4c6fff2da457ddc2f34", "03f09f5b158a7a8cdad920bddc29b81c18a551f5", "b06521f39153d618550606be297466d5" }, + { 64, "ffe054fe7ae0cb6dc65c3af9b61d5209f439851db43d0ba5997337df154668eb", "0098ba824b5c16427bd7a1122a5a442a25ec644d", "014842d480b571495a4a0363793f7367" }, + { 65, "635361c48bb9eab14198e76ea8ab7f1a41685d6ad62aa9146d301d4f17eb0ae0", "11655326c708d70319be2610e8a57d9a5b959d3b", "c743a45e0d2e6a95cb859adae0248435" }, + { 119, "31eba51c313a5c08226adf18d4a359cfdfd8d2e816b13f4af952f7ea6584dcfb", "ee971065aaa017e0632a8ca6c77bb3bf8b1dfc56", "8a7bd0732ed6a28ce75f6dabc90e1613" }, + { 120, "2f3d335432c70b580af0e8e1b3674a7c020d683aa5f73aaaedfdc55af904c21c", "f34c1488385346a55709ba056ddd08280dd4c6d6", "5f61c0ccad4cac44c75ff505e1f1e537" }, + { 121, "e9615320128cc7a3d6078e9af05603188e5ccbf0d07d8b735d3df5e8e0c1281f", "fa6b5a6f8ac27182f838fe7841ec6d2aef3ade29", "f6acfca2d47c87f2b14ca038234d3614" }, +}; + +// Message used by every vector: 'a' repeated len times +static unsigned char *MakeMessage(int len) +{ + unsigned char *msg = (unsigned char *)malloc(len + 1); + memset(msg, 'a', len); + msg[len] = 0; + return msg; +} + +// SHA-1/SHA-256 return 32-bit words holding the digest in big-endian reading order -> print each word as %08x +static void WordsToHex(const unsigned int *words, int count, char *out) +{ + for (int i = 0; i < count; i++) sprintf(out + i*8, "%08x", words[i]); +} + +// MD5 returns int[4] whose bytes in memory ARE the digest (little-endian words) -> print memory bytes +static void BytesToHex(const unsigned int *words, int byteCount, char *out) +{ + const unsigned char *bytes = (const unsigned char *)words; + for (int i = 0; i < byteCount; i++) sprintf(out + i*2, "%02x", bytes[i]); +} + +static void test_sha256_boundaries(void) +{ + char hex[65]; + + for (size_t i = 0; i < sizeof(vectors)/sizeof(vectors[0]); i++) + { + unsigned char *msg = MakeMessage(vectors[i].len); + WordsToHex(ComputeSHA256(msg, vectors[i].len), 8, hex); + printf(" sha256 len=%-3d %s\n", vectors[i].len, (strcmp(hex, vectors[i].sha256) == 0)? "ok" : "MISMATCH"); + CHECK_STR(vectors[i].sha256, hex); + free(msg); + } +} + +static void test_sha1_boundaries(void) +{ + char hex[41]; + + for (size_t i = 0; i < sizeof(vectors)/sizeof(vectors[0]); i++) + { + unsigned char *msg = MakeMessage(vectors[i].len); + WordsToHex(ComputeSHA1(msg, vectors[i].len), 5, hex); + CHECK_STR(vectors[i].sha1, hex); + free(msg); + } +} + +static void test_md5_boundaries(void) +{ + char hex[33]; + + for (size_t i = 0; i < sizeof(vectors)/sizeof(vectors[0]); i++) + { + unsigned char *msg = MakeMessage(vectors[i].len); + BytesToHex(ComputeMD5(msg, vectors[i].len), 16, hex); + CHECK_STR(vectors[i].md5, hex); + free(msg); + } +} + +static void test_crc32(void) +{ + // Standard CRC-32 check value (ISO-HDLC): CRC("123456789") == 0xCBF43926 + CHECK_INT(0xCBF43926u, ComputeCRC32((const unsigned char *)"123456789", 9)); + CHECK_INT(0x00000000u, ComputeCRC32((const unsigned char *)"", 0)); +} + +static void test_base64(void) +{ + // RFC 4648 section 10 test vectors + static const char *plain[] = { "", "f", "fo", "foo", "foob", "fooba", "foobar" }; + static const char *encoded[] = { "", "Zg==", "Zm8=", "Zm9v", "Zm9vYg==", "Zm9vYmE=", "Zm9vYmFy" }; + + for (int i = 0; i < 7; i++) + { + int len = (int)strlen(plain[i]); + int encLen = 0; + char *enc = EncodeDataBase64((const unsigned char *)plain[i], len, &encLen); + + CHECK_STR(encoded[i], enc); + + int decLen = 0; + unsigned char *dec = DecodeDataBase64(encoded[i], &decLen); + CHECK_INT(len, decLen); + CHECK(memcmp(dec, plain[i], len) == 0); + + MemFree(enc); + MemFree(dec); + } +} + +int main(void) +{ + SetTraceLogLevel(LOG_NONE); // Headless: no window is created, keep output clean + + RUN(test_sha256_boundaries); + RUN(test_sha1_boundaries); + RUN(test_md5_boundaries); + RUN(test_crc32); + RUN(test_base64); + + return RTEST_SUMMARY(); +} diff --git a/trabalho-raylib/06-implementacao/tests/test_paths.c b/trabalho-raylib/06-implementacao/tests/test_paths.c new file mode 100644 index 000000000000..e8e6e4a6a839 --- /dev/null +++ b/trabalho-raylib/06-implementacao/tests/test_paths.c @@ -0,0 +1,77 @@ +// Headless tests for the file-path helpers in rcore.c +// (GetFileName, GetFileExtension, IsFileExtension, GetFileNameWithoutExt, IsPathAbsolute) +// +// Regression context: raylib 6.2 CHANGELOG lists fixes in this area +// - GetFileExtension() returning the name of hidden files (PR #6326) +// - IsPathAbsolute() added in 6.2 and later changed to drop the isalpha() dependency + +#include "raylib.h" +#include "rtest.h" + +static void test_get_file_name(void) +{ + CHECK_STR("c.txt", GetFileName("a/b/c.txt")); + CHECK_STR("c.txt", GetFileName("a\\b\\c.txt")); // Both separators are handled + CHECK_STR("c.txt", GetFileName("c.txt")); + CHECK_STR("", GetFileName("a/b/")); // Directory path -> empty name + CHECK_STR(NULL, GetFileName(NULL)); +} + +static void test_get_file_extension(void) +{ + CHECK_STR(".png", GetFileExtension("sprite.png")); + CHECK_STR(".png", GetFileExtension("assets/img/sprite.png")); + CHECK_STR(".gz", GetFileExtension("archive.tar.gz")); // Only the last extension + CHECK_STR(NULL, GetFileExtension("README")); // No extension + CHECK_STR(NULL, GetFileExtension(".gitignore")); // Hidden file is not an extension (#6326) + CHECK_STR(NULL, GetFileExtension("project/.gitignore")); // Same, with a directory prefix (#6326) + CHECK_STR(NULL, GetFileExtension("my.dir/README")); // Dot in a directory name only + CHECK_STR(".txt", GetFileExtension("project/.hidden/a.txt")); +} + +static void test_is_file_extension(void) +{ + CHECK(IsFileExtension("sprite.png", ".png")); + CHECK(IsFileExtension("SPRITE.PNG", ".png")); // Case-insensitive + CHECK(IsFileExtension("sound.wav", ".png;.wav;.ogg")); // ';' separated list + CHECK(!IsFileExtension("sprite.png", ".wav")); + CHECK(!IsFileExtension("README", ".png")); +} + +static void test_file_name_without_ext(void) +{ + CHECK_STR("sprite", GetFileNameWithoutExt("assets/sprite.png")); + CHECK_STR("archive.tar", GetFileNameWithoutExt("archive.tar.gz")); +} + +static void test_is_path_absolute(void) +{ + CHECK(!IsPathAbsolute(NULL)); + CHECK(!IsPathAbsolute("")); + CHECK(!IsPathAbsolute("relative/path.txt")); + CHECK(!IsPathAbsolute("./relative.txt")); + +#if defined(_WIN32) + CHECK(IsPathAbsolute("C:\\Users\\raylib")); + CHECK(IsPathAbsolute("d:/games/raylib")); // Lowercase drive + forward slash + CHECK(IsPathAbsolute("\\\\server\\share\\file.txt")); // UNC path + CHECK(!IsPathAbsolute("C:")); // Drive without path is not absolute + CHECK(!IsPathAbsolute("C:file.txt")); // Drive-relative path +#else + CHECK(IsPathAbsolute("/usr/lib")); + CHECK(IsPathAbsolute("/")); +#endif +} + +int main(void) +{ + SetTraceLogLevel(LOG_NONE); + + RUN(test_get_file_name); + RUN(test_get_file_extension); + RUN(test_is_file_extension); + RUN(test_file_name_without_ext); + RUN(test_is_path_absolute); + + return RTEST_SUMMARY(); +} diff --git a/trabalho-raylib/06-implementacao/tests/test_utf8.c b/trabalho-raylib/06-implementacao/tests/test_utf8.c new file mode 100644 index 000000000000..f57b28a6e77f --- /dev/null +++ b/trabalho-raylib/06-implementacao/tests/test_utf8.c @@ -0,0 +1,73 @@ +// Headless tests for the UTF-8 helpers in rtext.c +// (GetCodepoint, GetCodepointCount, CodepointToUTF8) +// +// Regression test for PR #6348 "[rtext] Fix GetCodepoint() size on invalid sequences reading past the string end" +// Before that fix, on a truncated sequence codepointSize could be larger than the bytes left before the '\0', +// so a caller that advanced with text += codepointSize skipped the terminator and read out of bounds. + +#include "raylib.h" +#include "rtest.h" + +static void test_valid_sequences(void) +{ + int size = 0; + + CHECK_INT('A', GetCodepoint("A", &size)); CHECK_INT(1, size); + CHECK_INT(0xE9, GetCodepoint("\xC3\xA9", &size)); CHECK_INT(2, size); // U+00E9 (e acute) + CHECK_INT(0x20AC, GetCodepoint("\xE2\x82\xAC", &size)); CHECK_INT(3, size); // U+20AC (euro) + CHECK_INT(0x1F600, GetCodepoint("\xF0\x9F\x98\x80", &size)); CHECK_INT(4, size); // U+1F600 (emoji) +} + +static void test_invalid_sequences_return_question_mark(void) +{ + int size = 0; + + CHECK_INT('?', GetCodepoint("\x80", &size)); // Lone continuation byte + CHECK_INT('?', GetCodepoint("\xC3(", &size)); // Bad continuation byte + CHECK_INT('?', GetCodepoint("\xE0\x80\x80", &size)); // Overlong encoding + CHECK_INT('?', GetCodepoint("\xF5\x80\x80\x80", &size)); // Above U+10FFFF +} + +static void test_invalid_size_stays_inside_string(void) +{ + // Truncated sequences: "\xC3", "\xE2\x82", "\xF0\x9F\x98" followed by the terminator. + // A safe decoder never reports a size that goes beyond the terminating '\0' of the string. + const char *truncated[] = { "\xC3", "\xE2\x82", "\xF0\x9F\x98" }; + + for (int i = 0; i < 3; i++) + { + int size = 0; + GetCodepoint(truncated[i], &size); + CHECK(size <= (int)strlen(truncated[i])); + } +} + +static void test_codepoint_count(void) +{ + CHECK_INT(0, GetCodepointCount("")); + CHECK_INT(5, GetCodepointCount("hello")); + CHECK_INT(4, GetCodepointCount("a\xC3\xA9\xE2\x82\xAC\xF0\x9F\x98\x80")); // a, e acute, euro, emoji +} + +static void test_codepoint_to_utf8(void) +{ + int size = 0; + + CHECK_STR("A", CodepointToUTF8('A', &size)); CHECK_INT(1, size); + CHECK_STR("\xC3\xA9", CodepointToUTF8(0xE9, &size)); CHECK_INT(2, size); + CHECK_STR("\xE2\x82\xAC", CodepointToUTF8(0x20AC, &size)); CHECK_INT(3, size); + CHECK_STR("\xF0\x9F\x98\x80", CodepointToUTF8(0x1F600, &size)); CHECK_INT(4, size); +} + +int main(void) +{ + SetTraceLogLevel(LOG_NONE); + + RUN(test_valid_sequences); + RUN(test_invalid_sequences_return_question_mark); + RUN(test_invalid_size_stays_inside_string); + RUN(test_codepoint_count); + RUN(test_codepoint_to_utf8); + + return RTEST_SUMMARY(); +} diff --git a/trabalho-raylib/07-etica/07-etica.md b/trabalho-raylib/07-etica/07-etica.md new file mode 100644 index 000000000000..f9884bdc6aec --- /dev/null +++ b/trabalho-raylib/07-etica/07-etica.md @@ -0,0 +1,55 @@ +# 7 — Ética e responsabilidade + +## 1 — Segurança e responsabilidade sobre vulnerabilidades + +### O problema + +- **O raylib é base de outros produtos.** Jogos, ferramentas e +70 *bindings* embutem o código (`README.md:53`, `BINDINGS.md`); uma falha na biblioteca se propaga a todos os dependentes, que raramente têm como corrigi-la sozinhos. +- **Falhas de memória reais aparecem em funções "inocentes".** O PR **#6348** (aberto quando fizemos a análise; mesclado em 09/11/2026) descreve que `GetCodepoint()` pode devolver um tamanho que faz o chamador ler **além do `'\0'`** em UTF-8 truncado — a descrição do PR cita detecção por AddressSanitizer `[GH]`. Nós reproduzimos o sintoma no código de 31/10: 3 entradas truncadas devolviam tamanho > `strlen` (testes `XFAIL`); após o merge do PR, os mesmos testes passaram (`XPASS`) e foram promovidos a `CHECK` `[M]`. Também verificamos que `GetFileExtension(NULL)` derruba o processo (violação de acesso), enquanto funções vizinhas tratam `NULL` `[M]`. +- **Funções de integridade podem estar silenciosamente erradas.** `ComputeSHA256()` retornou hash incorreto para `tamanho mod 64 ∈ 56..59` (issue #6143 / PR #6144). Quem usou o hash para verificar integridade tinha uma garantia falsa. +- **O processo de divulgação é informal.** `SECURITY.md` manda reportar vulnerabilidades "diretamente em Issues e/ou Discussions" (públicas), e a tabela de versões suportadas lista `6.0.x` e `< 5.5` — **não menciona 6.2** (release de 15/10/2026), então está desatualizada `[L]`. Por outro lado, o projeto passou por **auditoria externa (ROS)** e tratou achados como `OpenURL()` (`CLN-002`) e eventos de automação (`CLN-005/006`) `[L]` `CHANGELOG:13,31-32`; roda CodeQL semanalmente (`analyze_codeql.yml`). + +### Responsabilidade do engenheiro de software + +1. **Tratar entrada externa como não confiável** (URLs, arquivos, strings UTF-8, caminhos) e validar limites — dever profissional, não só "boa prática". +2. **Divulgar com cuidado.** Um bug de leitura fora dos limites pode ser explorável; relatar publicamente sem avaliar o impacto pode expor usuários. O correto é seguir o canal que o projeto define **e** propor um canal privado (ex.: *GitHub Security Advisories*) quando houver risco de exploração. Antes de abrir qualquer issue sobre `GetFileExtension(NULL)`/`GetCodepoint`, a dupla deve **verificar** se já existe relato e avaliar se há risco real — **não afirmamos que haja vulnerabilidade explorável**, apenas comportamento incorreto reproduzido. +3. **Sinalizar mudanças que quebram contrato** (o `-WARNING-` do CHANGELOG é um bom exemplo) e **manter a política de suporte atualizada**. +4. **Verificar o que se publica.** Testes de regressão (nossa evolução) são a forma concreta de assumir responsabilidade: reduzem a chance de enviar defeitos conhecidos a terceiros. +5. **Honestidade sobre limites**: nossos testes foram executados no Windows/MSYS2 e no Linux (CI do GitHub, que falhou na 1ª execução e só ficou verde após um ajuste de dependências); **macOS não foi testado** — dizer isso é parte da responsabilidade. + +--- + +## 2 — Licenciamento e reuso de código de terceiros + +### O problema + +- O raylib é **zlib/libpng** (permissiva) — permite uso comercial, mas exige: não alegar autoria, **marcar versões alteradas**, manter o aviso (`LICENSE`; `rcore.c:71-88`). +- Ele **embute** ~266 mil linhas de bibliotecas com licenças **diferentes** em `src/external/` `[M]`. Verificamos nos cabeçalhos `[L]`: `miniaudio.h` — domínio público **ou** MIT-0 (`:2`); `stb_image.h` — domínio público/2 licenças (`:1`, `:7950`); `cgltf.h`, `par_shapes.h`, `tinyobj_loader_c.h` — **MIT** (exige preservar o aviso); `jar_xm.h` — licença **WTFPL v2** (`:3-11`); GLFW — `external/glfw/LICENSE.md`. O README remete à Wiki "raylib dependencies" para o quadro completo (`README.md:162`). +- Os exemplos usam **recursos** (imagens, sons, fontes) que precisam ter licença permissiva (exigência do fluxo do `rexm`, `tools/rexm/README.md:15`). +- **Nosso trabalho** cria um *fork* modificado e usa IA generativa para auxiliar: precisamos respeitar a cláusula 2 da zlib (versão alterada deve ser claramente marcada) e ser transparentes sobre autoria. + +### Responsabilidade do engenheiro de software + +1. **Conhecer e cumprir as obrigações de cada licença** ao redistribuir binários (ex.: reproduzir avisos MIT de `cgltf`/`par_shapes`/`tinyobj`), e **não assumir que "permissiva" = "sem obrigações"**. +2. **Rastrear dependências** e suas licenças (inventário/SBOM), e reavaliar a cada atualização de biblioteca embutida. +3. **Marcar claramente** o *fork* como alterado (`README.md` da dupla) e **não usar a marca/nome de forma enganosa**. +4. **Atribuição e IA:** declarar o uso de IA (`08-ia/ia.md`) e conferir que trecho gerado não reproduz código de licença incompatível; o código dos testes é nosso e é oferecido sob zlib, coerente com o projeto (o fork herda a licença zlib/libpng do raylib, arquivo `LICENSE` na raiz, com copyright de Ramon Santamaria (@raysan5)). +5. **Respeitar a licença dos recursos** (assets) incluídos em exemplos e não copiar documentação do projeto como se fosse própria (critério 13 do enunciado). + +--- + +## 3 — Acessibilidade e inclusão linguística (impacto social) + +### O problema + +- O raylib se apresenta como ferramenta de **educação** e é gratuito para escolas (`CONTRIBUTING.md:20`; `HISTORY.md`). Mas o próprio README declara a limitação: **o desenho de texto não suporta RTL, ligaduras nem emojis** (`README.md:65`) e a fonte padrão não consegue renderizar o caractere de substituição U+FFFD, por isso `GetCodepoint()` devolve `?` em erros (`src/rtext.c:2432-2436`) `[L]`. +- Efeito: textos em **árabe, hebraico** (direita-para-esquerda) e escritas que dependem de ligaduras/*shaping* **não são renderizados corretamente** pela biblioteca (inferência a partir da limitação declarada — não testamos esses idiomas); alunos e jogadores desses idiomas ficam à margem. O README também lista como limitação a rasterização de fontes inferior à de alternativas (`README.md:64`). +- Os jogos construídos herdam essas limitações; o projeto **não oferece APIs de acessibilidade** (leitor de tela, contraste, etc.) — coerente com a filosofia "sem interface, sem ajudantes visuais" (`README.md:7`), mas com impacto sobre pessoas com deficiência. + +### Responsabilidade do engenheiro de software + +1. **Ser transparente sobre limites** — o projeto faz isso no README; quem constrói produtos sobre ele deve repassar a informação aos usuários finais. +2. **Projetar para inclusão desde o início**: não tratar texto como "somente latino"; considerar internacionalização, contraste e alternativas de entrada em jogos e ferramentas educacionais. +3. **Priorizar de forma consciente**: o `ROADMAP.md` cita investigar o algoritmo *Slug* de renderização de fontes (`ROADMAP.md:27`); é uma oportunidade de melhoria com impacto social, e o engenheiro deve defender isso, com dados de usuários afetados, em vez de tratar como "luxo". +4. **Não prometer o que o sistema não entrega** (ex.: dizer que "suporta todos os idiomas"). + diff --git a/trabalho-raylib/08-ia/ia.md b/trabalho-raylib/08-ia/ia.md new file mode 100644 index 000000000000..38d8acdb5089 --- /dev/null +++ b/trabalho-raylib/08-ia/ia.md @@ -0,0 +1,90 @@ +# ia.md — Registro de uso de Inteligência Artificial + + +## 1. Ferramenta utilizada + +- **Claude Code** (extensão do VS Code), modelo **Claude Sonnet 5.5**, com acesso a leitura de arquivos, execução de comandos (PowerShell, gcc/MSYS2, Node) e consulta HTTP a `api.github.com`. +- Sessões de trabalho em **01/11/2026** (análise, relatório e testes) e **10/11/2026** (migração do relatório para o fork, atualização da branch, PR ao projeto original e checagem do que falta). `TODO: acrescentar outras ferramentas, se a dupla usar.` + +## 2. Objetivos + +| # | Objetivo | Seção do trabalho | +|---|---|---| +| 1 | Compreender a estrutura e o código do raylib (leitura de `rcore.c`, `rlgl.h`, `raylib.h`, platforms) | 3, 4, 5 | +| 2 | Pesquisar histórico no GitHub (releases, PRs, issues) | 3.2, 6 | +| 3 | Gerar rascunhos de requisitos, histórias, UML (Mermaid) e análise de impacto | 4, 5, 6 | +| 4 | Elaborar os testes da evolução e verificar compilação/execução | 7 | +| 5 | Revisão textual e organização do repositório | 10 | +| 6 | Passo a passo de comandos git/GitHub (migração para o fork, rebase, PR ao projeto original) e checagem do trabalho contra o enunciado | 7, 10, 11 | + +## 3. Principais prompts + +| Origem | Prompt (resumo fiel) | +|---|---| +| Dupla | "me ajude a fazer esse trabalho, baseando nessa pasta raylib-master" (com o PDF do enunciado anexado). | +| Dupla (resposta a pergunta da IA) | Evolução escolhida: **testes automatizados**. Destino: **nova pasta ao lado do raylib** (`trabalho-raylib/`). | +| IA → ferramentas | Leitura de `README.md`, `ROADMAP.md`, `CHANGELOG`, `CONTRIBUTING.md`, `CONVENTIONS.md`, `SECURITY.md`, `rcore.c`, `rtext.c`, `rlgl.h`, `raylib.h`, workflows; consultas à API do GitHub (`/releases`, `/commits`, `/issues`, `/pulls/NNNN`, `/search/issues`); compilação do raylib e dos testes; contagens de linhas. | +| Dupla (10/11) | "Preciso transferir tudo o que está na pasta do GitHub Trabalho-Raylib para a raylib (o fork), apagar o outro; o professor também pediu que a implementação seja enviada ao original para o dono aceitar — me explique como faz." | +| Dupla (10/11) | Colagens da saída do cmd, com perguntas como "deu tudo certo?", "o que aconteceu?" e "posso executar esses comandos antes de corrigir o erro?" (falha do workflow macOS). | +| Dupla (10/11) | "Faça o 5, o 6 e prepare o PR_DESCRIPTION.md atualizado, mas eu quero fazer os comandos do cmd." (a IA edita arquivos; a dupla executa o git). | +| Dupla (10/11) | "Verifique o que já está feito e o que falta" e, com o PDF do enunciado anexado: "pegue cada ponto e tópico e me indique onde está o trabalho, checando". | +| Dupla (10/11) | Perguntas de compreensão: "me explique os diagramas", "me explique o que é autor de binding", "onde encontro a licença do fork", "como fechar o PR #1", "o que é necessário na revisão", "sobre as evidências em implementação". | +| Dupla | `TODO: colar aqui os prompts adicionais que vocês escreverem (ex.: pedir ajustes, perguntar "por que X?").` | + +## 4. Resultados utilizados (e como foram verificados) + +| Resultado da IA | Como foi verificado (no próprio software) | +|---|---| +| Descrição das funcionalidades, licença, versão | Lidos no `README.md`, `LICENSE`, `raylib.h:89-92`, `CHANGELOG:4` — **citados com linha** nos documentos. | +| Estruturas e fluxos de UML | Cada elemento ligado a arquivo:linha (tabela de correspondências em `04-uml/`). **Sintaxe Mermaid validada** com o *parser* oficial (`mermaid@11` + `jsdom`: 5/5 blocos OK) — isso valida a sintaxe, **não** a fidelidade ao código, que foi conferida por leitura. | +| Contagens (310 entradas no changelog 6.2; ~130 autores; 70 do mantenedor; 15 `-WARNING-`; 59.590 vs 266.147 linhas; 228 exemplos) | Executadas por **scripts PowerShell** no snapshot local (`[M]`). A contagem de "autores distintos" inclui qualquer `@nome` na seção 6.2 (aproximação). | +| Dados do GitHub (datas, autores, merge) | Obtidos pela **API pública** via ferramenta de busca que **resume o JSON com um modelo menor** → sujeita a erro. Por isso conferimos individualmente #4869, #5264, #5266, #6348, #6326, #5664 e corrigimos divergências (item 5). **A dupla deve abrir cada link e conferir antes de apresentar.** | +| Código dos testes (`rtest.h`, `test_*.c`, `Makefile`) | **Compilado e executado** (gcc 14.2.0, MSYS2): 120 verificações, 0 falhas (3 XFAIL na 1ª execução; 0 após o merge do #6348, em 10/11). Vetores de hash vêm de **oráculo independente (.NET)**. **Teste de mutação** provou que detectam um `ComputeSHA256` quebrado (5 falhas, código de saída 1). | +| Achado: `GetFileExtension(NULL)` trava | **Reproduzido** com programa mínimo: código de saída `0xC0000005`. Causa lida em `rcore.c:2503-2504`. | +| Achado: `GetCodepoint` tinha o problema do PR #6348 | **Reproduzido** pelos 3 `XFAIL` (PR aberto na API em 01/11). O PR foi mesclado em 09/11 (commit `7e626d65`); em 10/11 os testes viraram `XPASS` e foram promovidos a `CHECK`. | +| Migração do relatório para `trabalho-raylib/` no fork `FaMarcolino/raylib` (branch `master`) | Conferida com git: 21 arquivos no fork = 21 no repositório antigo, sem diferença de nomes; o repositório antigo só foi apagado depois. | +| Rebase de `feat/headless-tests` sobre o `upstream/master` | `git rev-list --left-right --count` mostrou 38 commits de atraso e 7 de avanço; rebase sem conflito; `git ls-tree` confirmou que `tests/` e `run_tests.yml` não existiam no upstream; `make test` rodou pela dupla após o rebase: 120 verificações, `ALL TEST FILES PASSED`. | +| PR ao projeto original: **#6400** | Aberto pela dupla; conferido na página: 8 commits, título e descrição, base `raysan5/raylib:master`. **Desfecho:** o mantenedor o fechou sem mesclar em 10/11/2026 (comentário: "No, thanks.", sem motivo); os workflows do PR expiraram aguardando aprovação ("required approval but was not approved before it expired"). A IA **não** sabe o motivo da recusa. | +| Diagnóstico da falha do workflow macOS no PR #1 | Log colado pela dupla: "The job was not acquired by Runner of type hosted" (falha de infraestrutura do GitHub); as execuções manuais #4 (`master`) e #5 (`feat/headless-tests`) passaram. | +| Linhas `arquivo:linha` citadas no relatório | Conferidas na `master` do fork (`git show origin/master:src/rcore.c` etc.): `rcore.c:586`, `:863`, `:2500`, `:3509`, `:3545`, `rtext.c:2437` e `rlgl.h:420` batem; no raylib atual elas já mudaram. | +| Checagem do trabalho contra o enunciado (cada seção → arquivo) | Feita pela IA lendo os arquivos do repositório; a dupla deve reconferir. | + +## 5. Resultados descartados ou corrigidos durante o trabalho + +| O que a IA afirmou/fez | Por que foi descartado | Correção | +|---|---|---| +| Primeira busca por testes concluiu que **não havia `enable_testing`/`ctest`** em nenhum build file. | A busca usou um filtro de *glob* que **não alcançou** os arquivos; uma segunda busca, mais ampla, achou `enable_testing()` (`CMakeLists.txt:57`, `src/CMakeLists.txt:194`) e `ctest` no CI (`build_cmake.yml:67,111`). | Reformulamos o problema: "o `ctest` roda, mas **não há nenhum `add_test()`**". Também descobrimos o `rexm test` (smoke test de exemplos) e a issue #5664, e **removemos a frase "nenhum teste automatizado"** de todos os documentos, trocando por "nenhum teste das funções da biblioteca". | +| A IA citou **"issue/PR #6144"** (sem distinguir) nos comentários dos testes e nos textos iniciais. | Conferindo na API, **#6144 é PR** e a issue original é **#6143**. | Corrigido nos documentos e nos comentários de `test_hash.c`. | +| Uma consulta de busca da API devolveu para o **#6326** a data de criação **2025**, e só depois se autocorrigiu. | A data real é **24/10/2026** (e é PR). Isso mostra o risco de depender do resumo automático. | Corrigido; reforça o checklist da seção 7. | +| Dedução de que as PRs #5264 e #5266 "adicionaram" `ComputeSHA256`. | Só o **#5264** foi mesclado; **#5266** foi fechado sem merge. | Texto reescrito com os fatos. | +| Frase "`GetFPS` é função pura". | `GetFPS()` depende de tempo/estado; não é pura e **não** está nos testes. | Removida da lista de funções puras. | +| A IA sinalizou como possível inconsistência "6.2 (CHANGELOG) vs 6.5-dev (`raylib.h`)". | Não é erro: o `master` avançou além da última release publicada (o snapshot contém o commit `2f4b7d8` de 31/10/2026). | Explicado em `01-discovery/`. | +| Ideia de **ligar os testes ao `ctest`** já no MVP. | Não há CMake neste ambiente para **verificar**. | Mantido como "próximo passo", sem afirmar que funciona. | +| A IA redigiu a descrição do PR ao raylib em inglês, longa e detalhada (evidências, checklist). | O GitHub avisou que o `CONTRIBUTING.md` ganhou a seção "About AI Usage": pede descrição curta, não gerada por IA, e que o contribuidor conheça o contexto. | Texto reescrito curto; a dupla deve adaptá-lo com as próprias palavras; o PR mantém a declaração de uso de IA. | +| A IA sugeriu sincronizar a `master` do fork com o `upstream` para evitar builds no PR #1. | Quebraria as referências `arquivo:linha` do relatório (as linhas mudaram no upstream). | Sugestão retirada: a `master` do fork permanece no snapshot de 31/10. | +| A IA sugeriu o comentário "Review done here" para fechar o PR #1. | Falso: a revisão pelo outro integrante ainda não foi feita. | Erro reconhecido; a dupla deve editar o comentário (ver `REVISAO.md`). | +| A IA indicou a revisão no PR #1. | O PR #1 tem base antiga: 45 commits e comentários do CodeQL sobre arquivos que a dupla não alterou. | Código revisado a partir do diff do PR #6400 (7 arquivos; PR depois fechado pelo mantenedor) e da branch do fork; registro da revisão no fork. | +| A IA passou ao revisor o comando do teste de mutação sem indicar onde gravar a biblioteca. | O Makefile do raylib grava `libraylib.a` em `../src/` (`RAYLIB_RELEASE_PATH ?= ../src`): a cópia `src_mut` ficou com a biblioteca original, os testes passaram e a mutação não foi exercitada; a biblioteca original foi sobrescrita pela versão mutada. | Reconstruir a biblioteca original e refazer a mutação com `RAYLIB_RELEASE_PATH=.`; roteiro do `REVISAO.md` corrigido. | + +## 6. O que a IA **não** fez / limites + +- **Não** criou o repositório no GitHub nem o *fork* (feitos pela dupla), **não** abriu o **PR** nem fez a **revisão pelo outro integrante**. A IA instalou o Git (a pedido da dupla), clonou o fork e fez os commits localmente com a identidade informada pela dupla; o `git push` e o login no GitHub foram feitos pela dupla. +- **Não** executou o CMake. O workflow `run_tests.yml` (CI Linux) rodou no fork: a **1ª execução falhou** no passo "Run tests" (`exit code 2`). A IA não conseguia ler o log (exige login) e levantou a **hipótese** de falta de `libglfw3-dev` (que os workflows oficiais instalam). A dupla colou o log real, que **confirmou**: `/usr/bin/ld: cannot find -lGL` (erro de link, não de teste). Após o ajuste (commit `b83e2d3`) a execução ficou **verde**. +- **Não** validou a escolha do software com o professor. +- Em **10/11** a IA **só editou arquivos** locais e leu informações (comandos `git` de leitura e páginas públicas do GitHub). Os comandos que alteram o GitHub — `commit`, `push`, rebase, apagar o repositório `Trabalho-Raylib`, abrir o PR #6400 e fechar o PR #1 — foram **executados pela dupla** no cmd e no navegador. A IA também **não** viu logs que exigem login: dependeu da dupla colá-los. +- Personas são **arquétipos derivados de documentos**, não entrevistas. +- Os testes foram executados no **Windows/MSYS2** (local) e no **Linux/Ubuntu** (CI do GitHub). **macOS não foi executado.** + +## 7. Checklist de verificação que a dupla deve fazer ANTES da apresentação + +- [ ] Abrir os links e conferir número/título/autor/data de: #4869, #5264, #5266, #6143, #6144, #6312, #6326, #6348, #5664, #6351, releases 5.5/6.0/6.2. +- [ ] Rodar `make test` por conta própria e ver os 120 checks. +- [ ] Rodar o teste de mutação do `REVISAO.md` (seção D) e ver falhar. +- [ ] Abrir 5 linhas citadas (ex.: `rcore.c:586`, `:3545`, `:2500`, `rtext.c:2437`, `rlgl.h:420`) e confirmar o conteúdo no commit do fork. +- [ ] Conseguir explicar sem consultar: o que `InitPlatform()` faz; por que `GetFileExtension(".gitignore")` é `NULL`; o que é XFAIL/XPASS; por que o teste é *headless*. +- [ ] Reler cada documento e **reescrever com suas palavras** o que não souberem defender (o enunciado permite perguntas individuais). +- [ ] Preencher todos os `TODO` (nomes, ferramentas e prompts da dupla). +- [ ] Abrir o PR #6400 e conferir o desfecho: fechado pelo mantenedor em 10/11 com o comentário "No, thanks." (sem mesclar), e saber explicar isso. +- [ ] Reler a seção "About AI Usage" do `CONTRIBUTING.md` do raylib e adaptar a descrição do PR com as próprias palavras. +- [ ] Conferir que o comentário de fechamento do PR #1 não afirma uma revisão que ainda não aconteceu. +- [ ] Abrir 2 ou 3 linhas `arquivo:linha` na `master` do **fork** (não no upstream atual) e conferir o conteúdo. diff --git a/trabalho-raylib/README.md b/trabalho-raylib/README.md new file mode 100644 index 000000000000..739c2141ba3f --- /dev/null +++ b/trabalho-raylib/README.md @@ -0,0 +1,70 @@ +# Software Archaeology — raylib + +Trabalho Prático de **CSI412 – Engenharia de Software I** (UFOP/ICEA/DECSI, 2026/2, Prof. Igor Muzetti Pereira). + +| | | +|---|---| +| **Integrantes** | `Fabian Givanna Marcolino dos Santos` · `Luan Henrique Pais` | +| **Software analisado** | **raylib** — biblioteca C para programação de jogos | +| **Projeto original** | https://github.com/raysan5/raylib | +| **Licença do projeto** | zlib/libpng (`LICENSE`) | +| **Versão analisada** | Release estável **6.2** (tag `6.2`, 15/10/2026) + snapshot do `master` de 31/10/2026 (`RAYLIB_VERSION "6.5-dev"`, commit `2f4b7d8` ou posterior) | +| **Fork com a intervenção** | https://github.com/FaMarcolino/raylib (branch `feat/headless-tests`; commit base da análise `2f4b7d8e9f4aef3d5ed81a683b54594849e9d7a7`; após o rebase de 10/11/2026 a branch está sobre `0dedaf3066ffd0a63b5899385f59055a915f839c`) | +| **Pull Request ao projeto original** | https://github.com/raysan5/raylib/pull/6400 (aberto em 10/11/2026 e **fechado pelo mantenedor no mesmo dia, sem mesclar** — único comentário: "No, thanks."; revisão interna no fork: https://github.com/FaMarcolino/raylib/pull/1) | + + +## Objetivo do trabalho + +Assumir o papel de uma equipe que entra em um projeto existente: compreender o software, seus usuários, requisitos, +código, processo de desenvolvimento e histórico — e então **justificar tecnicamente e implementar experimentalmente** uma pequena evolução. + +## Resumo da proposta de evolução + +**Problema (evidência):** o raylib não tem nenhum teste automatizado. O CI (12 workflows) só compila e roda análise estática +(clang-tidy, CodeQL); nenhum workflow executa testes. Em consequência, bugs em funções puras e simples chegam a usuários e são +corrigidos depois — por exemplo `ComputeSHA256()` retornando hash errado para mensagens de 56–59 bytes (issue #6143 / PR #6144) e +`GetFileExtension()` corrigida duas vezes em 3 dias (PRs #6312 e #6326). + +**Proposta:** criar uma suíte de **testes de regressão headless** (sem janela/GPU) para o núcleo utilitário da biblioteca, executável +com `make test` e integrada ao CI. + +**Intervenção experimental (pasta `06-implementacao/`):** 3 arquivos de teste, **120 verificações**, mais um mini-helper (`rtest.h`), +Makefile e workflow de CI. Foi verificado por *teste de mutação* que os testes detectam um `ComputeSHA256` quebrado. + +## Como executar a intervenção + +Pré-requisitos: compilador C (gcc/clang) e `make` (no Windows: MSYS2 `mingw32-make`). + +```bash +# 1) Na raiz do fork do raylib, compile a biblioteca estática +cd src +make PLATFORM=PLATFORM_DESKTOP # Windows/MSYS2: mingw32-make PLATFORM=PLATFORM_DESKTOP + +# 2) Rode os testes +cd ../tests +make test # Windows/MSYS2: mingw32-make test +``` + +Detalhes em [`06-implementacao/README.md`](06-implementacao/README.md). + +## Estrutura do repositório + +| Pasta | Conteúdo | Seção do enunciado | +|---|---|---| +| [`01-discovery/`](01-discovery/01-software.md) | O que é o software, personas e JTBD | 1.1 | +| [`02-processo/`](02-processo/02-evolucao-e-processo.md) | Evolução, práticas e processos de software | 2.2 | +| [`03-requisitos/`](03-requisitos/03-requisitos.md) | Requisitos, histórias de usuário e cenários | 3 | +| [`04-uml/`](04-uml/04-uml.md) | 5 diagramas UML + correspondências com o código | 4 | +| [`05-evolucao/`](05-evolucao/05-evolucao.md) | Proposta, MVP e análise de impacto | 5 | +| [`06-implementacao/`](06-implementacao/README.md) | Testes, CI, descrição do PR e revisão | 6 | +| [`07-etica/`](07-etica/07-etica.md) | Questões éticas | 7 | +| [`08-ia/`](08-ia/ia.md) | Uso de IA (`ia.md`) | 8 | + + +## Convenção de evidências + +Cada afirmação traz sua origem: + +- **`[L]`** = verificado no código/arquivos locais do snapshot (`arquivo:linha`). +- **`[GH]`** = verificado no GitHub (issue/PR/release/commit, com URL ou número). +- **`[M]`** = medido/executado por nós (compilação, testes, contagens).