feat(rust): Lexis e Codex avançados para desenvolvimento agêntico em Rust#1
feat(rust): Lexis e Codex avançados para desenvolvimento agêntico em Rust#1Fernando Seguim (fernandoseguim) wants to merge 2 commits into
Conversation
Adiciona 4 Lexis e 5 Codex para guiar o desenvolvimento agêntico em Rust,
baseados nos ensinamentos de Andrew Gallant (BurntSushi) e nas melhores
práticas do ecossistema Rust.
## Lexis (Leis Inquebráveis)
- lex-rust-no-panic-in-production: proíbe unwrap/panic em erros recuperáveis
- lex-rust-no-assume-utf8-on-io: proíbe assumir UTF-8 em I/O não validado
- lex-rust-no-regex-compilation-in-loops: proíbe compilar Regex em loops
- lex-rust-library-must-define-error-type: bibliotecas devem ter tipo de erro próprio
## Codex (Manuais de Referência)
- codex-rust-error-handling: Result, Option, thiserror, anyhow, operador ?
- codex-rust-performance-and-search: busca em camadas, SIMD, NFA/DFA, FST
- codex-rust-api-design: Builder pattern, tipos genéricos, dois níveis de API
- codex-rust-burntsushi-ecosystem: mapa de crates (regex, memchr, bstr, fst, etc.)
- codex-rust-oss-maintenance: sustentabilidade OSS, SemVer, limites saudáveis
Fontes: burntsushi.net (error-handling, unwrap, bstr, regex-internals,
ripgrep, transducers, csv, foss, projects)
…referência Adiciona 4 novos Lexis e 2 novos Codex para desenvolvimento em Rust, derivados do estudo profundo de 5 repositórios de referência da indústria: ripgrep, tokio, alacritty, meilisearch e tikv. ## Novos Lexis (Leis Inquebráveis) - lex-rust-unsafe-isolation: blocos unsafe DEVEM ter comentário SAFETY: e encapsulamento em Safe Abstraction (padrão TiKV/Alacritty) - lex-rust-no-blocking-in-async: proíbe I/O síncrono e CPU-bound em contextos assíncronos sem spawn_blocking (padrão Tokio/Meilisearch) - lex-rust-library-error-types: bibliotecas DEVEM definir tipos de erro próprios; proíbe anyhow em APIs públicas (padrão Meilisearch/Ripgrep) - lex-rust-non-exhaustive-types: tipos públicos extensíveis DEVEM usar #[non_exhaustive] para evolução sem breaking changes (padrão Ripgrep) ## Novos Codex (Manuais de Referência) - codex-rust-async-architecture: Tokio, task spawning, JoinSet, graceful shutdown, actor pattern, cancellation safety, select! patterns - codex-rust-system-design: Workspaces, batching, event loops, engine traits, FSM, observabilidade com tracing, newtype pattern ## Atualizado - README.md: índice completo com todos os 7 Lexis e 7 Codex Fontes: ripgrep, tokio, alacritty, meilisearch, tikv, burntsushi.net
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! Este pull request enriquece o framework Ahrena com um conjunto abrangente de guias para o desenvolvimento agêntico em Rust. Os novos artefatos, categorizados como "Lexis" (leis inquebráveis) e "Codex" (manuais de referência), destilam as melhores práticas de projetos Rust de classe mundial e do ecossistema BurntSushi, visando elevar a qualidade, performance e sustentabilidade do código Rust, tanto para desenvolvedores humanos quanto para agentes de IA. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on Gemini (@gemini-code-assist) comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
Este PR introduz um excelente conjunto de guias (Lexis e Codex) para o desenvolvimento em Rust, baseados em práticas consolidadas da indústria. A documentação é detalhada, bem estruturada e cobre tópicos cruciais de arquitetura, performance e segurança. As leis (Lexis) são claras e os manuais (Codex) fornecem um ótimo contexto. Fiz algumas sugestões pontuais para melhorar a clareza e precisão em alguns documentos, principalmente relacionados à formulação de uma das leis e à concisão do texto. No geral, é uma adição de altíssimo valor para o framework.
Note: Security Review has been skipped due to the limited scope of the PR.
| #### 3. Select e Cancellation Safety | ||
| O macro `tokio::select!` avalia múltiplas futures simultaneamente. Quando uma termina, as outras são *dropadas*. Apenas use em branches futures que são "Cancellation Safe" (ex: `mpsc::Receiver::recv`). | ||
|
|
||
| **Perigo:** Ler de um stream de bytes (`AsyncReadExt::read`) não é cancellation safe. Se a future for dropada no meio da leitura, bytes podem ser perdidos. |
There was a problem hiding this comment.
A explicação sobre o perigo de AsyncReadExt::read não ser "cancellation safe" está correta, mas poderia ser mais construtiva. Apenas apontar o perigo sem oferecer uma solução ou um padrão mais seguro pode deixar o leitor sem saber como agir. Seria útil adicionar uma nota sobre como mitigar esse risco, por exemplo, usando leitores com buffer (tokio::io::BufReader) e métodos que operam sobre o buffer de uma forma que seja segura em caso de cancelamento, ou estruturando o código para que a operação de leitura não seja cancelada no meio.
|
|
||
| ### Princípios | ||
|
|
||
| 1. **Arquitetura Orientada a Crates (Workspaces):** Sistemas grandes em Rust não devem ser monólitos monolíticos de código. Devem ser divididos em múltiplos *crates* usando o recurso de `[workspace]` do Cargo. Isso melhora os tempos de compilação, impõe fronteiras de dependência estritas e facilita testes isolados (ex: `ripgrep` possui crates `core`, `regex`, `searcher`; `meilisearch` possui `index-scheduler`, `milli`, etc). |
There was a problem hiding this comment.
A expressão "monólitos monolíticos" é redundante. Usar apenas "monólitos" é suficiente e torna a frase mais concisa.
| 1. **Arquitetura Orientada a Crates (Workspaces):** Sistemas grandes em Rust não devem ser monólitos monolíticos de código. Devem ser divididos em múltiplos *crates* usando o recurso de `[workspace]` do Cargo. Isso melhora os tempos de compilação, impõe fronteiras de dependência estritas e facilita testes isolados (ex: `ripgrep` possui crates `core`, `regex`, `searcher`; `meilisearch` possui `index-scheduler`, `milli`, etc). | |
| 1. **Arquitetura Orientada a Crates (Workspaces):** Sistemas grandes em Rust não devem ser monólitos de código. Devem ser divididos em múltiplos *crates* usando o recurso de `[workspace]` do Cargo. Isso melhora os tempos de compilação, impõe fronteiras de dependência estritas e facilita testes isolados (ex: `ripgrep` possui crates `core`, `regex`, `searcher`; `meilisearch` possui `index-scheduler`, `milli`, etc). |
| @@ -0,0 +1,70 @@ | |||
| # Lexis: Tipos de Erro Específicos para Bibliotecas e Roteadores | |||
There was a problem hiding this comment.
O termo "Roteadores" no título parece específico demais e um pouco deslocado, já que o documento aborda um princípio geral de design de API para bibliotecas e módulos públicos, não apenas roteadores de frameworks web. Um título mais genérico, como "Tipos de Erro Específicos para APIs Públicas" ou "Tipos de Erro Específicos para Bibliotecas", estaria mais alinhado com o escopo e o conteúdo da lei.
| # Lexis: Tipos de Erro Específicos para Bibliotecas e Roteadores | |
| # Lexis: Tipos de Erro Específicos para APIs de Bibliotecas |
| A segurança de memória é a principal garantia da linguagem Rust. O uso da palavra-chave `unsafe` desativa essas garantias, transferindo a responsabilidade do compilador para o desenvolvedor. Se o código `unsafe` não for devidamente isolado e encapsulado em abstrações seguras, a integridade de toda a aplicação (como visto em sistemas críticos como TiKV e renderizadores como Alacritty) é comprometida. Esta lei garante que o `unsafe` seja auditável e não "vaze" para a API pública. | ||
|
|
||
| ## Lei | ||
| > **Todo bloco ou função `unsafe` DEVE ser encapsulado em uma API segura (`Safe Abstraction`) e DEVE conter um comentário `// SAFETY:` documentando explicitamente por que a operação é segura e quais invariantes o chamador deve garantir.** |
There was a problem hiding this comment.
A formulação da lei, especificamente a parte "...e quais invariantes o chamador deve garantir", pode ser confusa. O objetivo de encapsular um bloco unsafe em uma API segura é justamente remover do chamador a responsabilidade de garantir invariantes. A função segura é que deve garantir que as precondições do bloco unsafe sejam atendidas. A frase atual parece mais aplicável a funções unsafe públicas, não a blocos unsafe dentro de funções seguras. Sugiro reformular para focar nos invariantes que o próprio código deve manter para que a operação seja segura.
| > **Todo bloco ou função `unsafe` DEVE ser encapsulado em uma API segura (`Safe Abstraction`) e DEVE conter um comentário `// SAFETY:` documentando explicitamente por que a operação é segura e quais invariantes o chamador deve garantir.** | |
| > **Todo bloco ou função `unsafe` DEVE ser encapsulado em uma API segura (`Safe Abstraction`) e DEVE conter um comentário `// SAFETY:` documentando explicitamente por que a operação é segura e quais invariantes estão sendo mantidos pelo código circundante para garantir essa segurança.** |
Fernando Seguim (fernandoseguim)
force-pushed
the
main
branch
from
559a1f0 to
99e2019
Compare
[en] Two BLOCKERs and four actionable WARNINGs from Argos's PR #82 multi-axis review addressed. BLOCKER #1 — _ensure_server_in_directives EOF-no-newline (scripts/mcp_enable.py) The active-block capture stopped at the first newline-terminated entry, causing a new server to be inserted in the middle of an existing list whenever the .directives file ended without a trailing newline. The symmetric BLOCKER #2 on _remove_server_from_directives was already resolved in 2d1fd4b via gemini's (?:\n|$) suggestion. Fix here: _ACTIVE_BLOCK_RE now also accepts (?:\n|$), and the function normalises the captured body to end with \n before appending the new entry, so the result lands at the end of the list independent of input formatting. WARNING — install_tool shell-injection surface (scripts/preflight.py) Switched from subprocess.run(cmd, shell=True) to shlex.split(cmd) + shell=False. Today's install_hints values are framework-owned constants and safe; the change removes the foothold for any future consumer that might compose a ToolSpec from non-static input. Contract documented in the function docstring. WARNING — unresolved-requires UX (scripts/mcp_enable.py) Argos suggested a milder default than always-fatal: keep fatal under --non-interactive (CI must never proceed past unknown deps), but prompt "Proceed anyway? [y/N]" in interactive sessions so a known-safe entry can still be skipped. Implemented; default answer is no. WARNING — Python executable name testability (scripts/preflight.py) Extracted _python_executable_name() helper from the inline conditional inside the PYTHON ToolSpec, so the Windows/POSIX branches can be monkeypatched in tests without reloading the module. WARNING — new code untested (tools/ahrena-mcp/tests/) Two new test files cover the bug fixtures Argos surfaced plus the core helpers that future contributions can regress: 30 tests across preflight (Python name resolution, parse_semver, detect_os, check_tool present/absent/too-old, install_tool no-hint/dry-run/shell=False) and mcp_enable (ensure idempotent / appends / EOF-no-newline / commented block / no-block; remove present/absent/EOF-no-newline; requires resolver known/unknown; platform-config cleanup present/absent/missing files). All 30 pass; existing 19 tests in test_install_mcp + test_parse_directives also still pass. Out of scope for this round (Argos flagged for follow-up): ES translation backfill in codex-mcp-{github,notion,figma} (pre-existing gap inherited by this PR) and VM-clean bootstrap validation. Refs #81 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…rves history) [en] Per plan-046 Step 14 / Open Question #1: moves the historical archive of completed plans (pre-ADR-002 model) to .issues/_legacy/ via git mv, preserving git blame/log. Adds README declaring the directory as frozen history — no editing, no new files. Plans created after ADR-002 live as GitHub Issue bodies; .plans/{N}.md (gitignored) is the AI's working memory cache. [pt-BR] Per plan-046 Step 14 / OQ#1: move o histórico de planos pré-ADR-002 para .issues/_legacy/ via git mv, preservando history. README declara o diretório como congelado. Refs #96 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…handler (3 langs) [en] Per user request, redesigns the kata-pr-prepare loop into 3 explicit stages: - Step 6c (Phase A — Argos pre-flight cycles): up to 3 interactive cycles gated by AskUserQuestion. Each cycle: ask → invoke Argos → read findings → Athena addresses P0 (mandatory) / P1 (asked) / P2 (note) → commit + push → next cycle. User can stop early via (b) skip-to-human or (c) stop entire flow. - Step 6d (Phase B — Human nudge loop): 3 cycles via ScheduleWakeup (or cron / manual per option a/b/c). Each cycle fires a Slack notification with escalating urgency (H1 "ready", H2 "reminder #1", H3 "reminder #2, 2nd nudge"). Loop closes on APPROVED, merged, CHANGES_REQUESTED, or H3 silent exit. - Step 6e (Phase C — CHANGES_REQUESTED handler): on changes requested, Athena addresses (or defers) and RESTARTS the loop from Phase A (new HEAD invalidates previous Argos review). Also updates codex-agent-planning §10 summary to describe the 3-stage flow. Re-syncs .claude/ + .cursor/ from framework/en/. [pt-BR] Reorganiza o loop em 3 fases: Fase A (Argos cycles interativos), Fase B (Human nudge loop com notificações Slack escalonadas), Fase C (CHANGES_REQUESTED reseta para Fase A). Refs #96 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 participant
Resumo
Este PR adiciona um conjunto completo de artefatos Ahrena para guiar o desenvolvimento agêntico em Rust, derivados do estudo profundo de 5 repositórios de referência da indústria e do blog de Andrew Gallant (BurntSushi).
Fontes de Conhecimento Estudadas
#[non_exhaustive]Novos Artefatos
Lexis (Leis Inquebráveis)
lex-rust-unsafe-isolationunsafeDEVEM ter comentário// SAFETY:e encapsulamentolex-rust-no-blocking-in-asynclex-rust-library-error-typesanyhowem APIs públicaslex-rust-non-exhaustive-types#[non_exhaustive]Codex (Manuais de Referência)
codex-rust-async-architecturecodex-rust-system-designREADME
Índice completo com todos os 7 Lexis e 7 Codex, incluindo os artefatos da v1 (já na main).
Checklist