Ts/clean

[tcrypt25519]

No description provided.

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
crates/jet_ir/src/lib.rs	28% smaller
crates/jet_runtime/src/lib.rs	9% smaller
crates/jet_runtime/src/exec.rs	6% smaller
README.md	Unsupported file format
crates/jet/src/builder/env.rs	0% smaller
crates/jet/src/builder/manager.rs	0% smaller
crates/jet/src/builder/mod.rs	0% smaller
crates/jet/src/engine/mod.rs	0% smaller
crates/jet/src/instructions.rs	0% smaller
crates/jet/src/lib.rs	0% smaller
crates/jet_ir/src/constants.rs	0% smaller
crates/jet_ir/src/types.rs	0% smaller
crates/jet_runtime/src/error.rs	0% smaller
docs/architecture/architecture.md	Unsupported file format
docs/architecture/philosophy.md	Unsupported file format
docs/process/new-runtime-function.md	Unsupported file format
docs/test_coverage.md	Unsupported file format

[gemini-code-assist]

Summary of Changes

Hello @tcrypt25519, I'm Gemini Code Assist¹! 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!

This pull request focuses on a significant cleanup and documentation effort across the Jet project. The primary goal was to enhance code readability, clarify the system's architecture, and streamline development workflows. Key changes include adding comprehensive Rustdoc comments, updating core documentation, refactoring the runtime IR generation to be programmatic, and introducing a dedicated crate for shared LLVM types. These improvements aim to make the codebase more accessible and easier to contribute to, while also providing clearer guidance for future development and testing.

Highlights

• Comprehensive Documentation Update: Extensive Rustdoc comments were added across the jet, jet_ir, and jet_runtime crates, significantly improving code clarity and maintainability for structs, enums, methods, and modules.
• Architectural and Project Structure Clarification: The README.md and docs/architecture/architecture.md files received major updates, detailing the project's architecture, compilation pipeline, repository structure, and development processes. This includes updating the description of cooperating components to reflect the new jet_ir crate.
• Runtime IR Generation Refactoring: The static runtime-ir/jet.ll file was replaced by programmatic LLVM IR generation within jet_runtime::RuntimeBuilder. This change enhances portability, eliminates host target triple mismatches, and ensures better synchronization between Rust types and generated IR.
• Introduction of Shared IR Crate: A new jet_ir crate was introduced to centralize shared LLVM types and constants. This ensures consistent memory layouts and type definitions across both the compiler and runtime components, preventing layout drift.
• New Development Process and Test Coverage Documentation: New process documentation was added for integrating runtime functions (docs/process/new-runtime-function.md), and a detailed test coverage report (docs/test_coverage.md) was introduced to track opcode implementation and testing status.

Changelog

• README.md
  • Updated project title and added badges for Rust, LLVM, License, and CI status.
  • Expanded the project description to include target high-performance scenarios.
  • Revised the 'Project Goals' into a new 'Architecture' section detailing the four cooperating components and compilation pipeline.
  • Updated 'Getting Started' with prerequisites, build instructions, and jetdbg usage.
  • Added sections for 'Run the test suite', 'Platform notes', and a detailed 'Repository Structure'.
  • Introduced a 'Development' section linking to the full development guide.
• crates/jet/src/builder/env.rs
  • Added Rustdoc comments to the Options struct, its new constructor, and accessor methods (mode, emit_llvm, assert).
  • Added Rustdoc comments to the Mode enum and its variants.
  • Added Rustdoc comments to the Env struct, its new constructor, and accessor methods (context, module, opts).
• crates/jet/src/builder/manager.rs
  • Added Rustdoc comments to the Manager struct, its new constructor, env accessor, and add_contract_function method.
• crates/jet/src/builder/mod.rs
  • Added module-level Rustdoc comments for contract, env, and manager.
  • Added Rustdoc comments to the InvalidOpcode struct and its fields.
  • Added Rustdoc comments to the Error enum and its variants, and the invariant_violation constructor.
• crates/jet/src/engine/mod.rs
  • Added Rustdoc comments to the Error enum and its variants.
  • Added Rustdoc comments to the Engine struct, its new constructor, build_contract method, and run_contract method.
• crates/jet/src/instructions.rs
  • Added Rustdoc comments to the Instruction enum, its opcode, is_push, and push_len methods.
  • Added Rustdoc comments to the Iter struct and its new constructor.
  • Added Rustdoc comments to the IterItem enum and its variants.
• crates/jet/src/lib.rs
  • Added crate-level Rustdoc for the jet library.
  • Added module-level Rustdoc comments for builder, engine, and instructions.
• crates/jet_ir/src/constants.rs
  • Added Rustdoc comments to all public constants including WORD_SIZE_BYTES, STACK_SIZE_WORDS, ADDRESS_SIZE_BYTES, BLOCK_HASH_HISTORY_SIZE, MEMORY_INITIAL_SIZE_WORDS, STORAGE_INITIAL_SIZE_WORDS, and SUB_CALL_RETURN_MAX_SIZE_WORDS.
• crates/jet_ir/src/lib.rs
  • Added crate-level Rustdoc for the jet_ir library.
  • Changed pub mod constants and pub mod types to mod constants and mod types for better encapsulation.
• crates/jet_ir/src/types.rs
  • Added Rustdoc comments to all fields of the Types struct, describing their purpose and LLVM type mapping.
• crates/jet_runtime/src/error.rs
  • Added Rustdoc comment to the Result type alias.
• crates/jet_runtime/src/exec.rs
  • Added Rustdoc comments to type aliases Word, Hash, HashHistory, and ContractFunc.
  • Added Rustdoc comments to the Context struct, its new constructor, and accessor methods.
  • Added Rustdoc comments to the ContractRun struct, its new constructor, and accessor methods.
  • Added Rustdoc comments to the BlockInfo struct, its new constructor, and accessor methods.
  • Added Rustdoc comments to the ReturnCode enum and its variants.
• crates/jet_runtime/src/lib.rs
  • Added crate-level Rustdoc for the jet_runtime library.
  • Added module-level Rustdoc comments for address, builtins, error, exec, runtime_builder, and symbols.
  • Changed pub mod binding to mod binding.
• docs/architecture/architecture.md
  • Updated the 'Architecture' section to reflect four cooperating components, including jet_ir and jet_push_macros.
  • Revised the 'Crate Structure' diagram to include jet_ir and jet_push_macros.
  • Replaced the 'Function Declaration Pattern' with 'RuntimeBuilder: Programmatic IR Generation', detailing the new approach for runtime function generation.
  • Removed the 'Special Case: IR-Defined Runtime Function' section.
  • Updated the 'Execution Context Layout' to clarify pointer-based memory and LLVM field indices.
  • Updated 'Adding a New Runtime Function' to refer to the new process document.
  • Revised 'Known TODOs and Constraints' to reflect resolved issues and current limitations.
  • Updated 'Future Optimization Opportunities' and 'Suggested Next Steps'.
  • Modified the 'Task' table to reflect changes in file responsibilities for adding runtime functions and modifying context/constants.
• docs/architecture/philosophy.md
  • Renamed docs/architecture/manifesto.md to docs/architecture/philosophy.md.
  • Updated the document title from 'Manifesto' to 'Design Patterns'.
• docs/process/new-runtime-function.md
  • Added a new document outlining the step-by-step process for adding a new runtime function to Jet, including checklist items and common pitfalls.
• docs/test_coverage.md
  • Added a new document providing a summary of test coverage by category and opcode.
  • Included a quick opcode lookup table with testing status and notes.
  • Provided a quick reference for the test framework, including basic structure, helper macros, and TestContractRun fields.

Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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-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

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a substantial cleanup and documentation overhaul, significantly enhancing the project's clarity, maintainability, and developer experience. Key changes include a comprehensive rewrite of the main README.md, the addition of extensive rustdoc comments across the jet, jet_ir, and jet_runtime crates, and major updates to the architecture documentation to reflect recent refactoring. The introduction of new process and test coverage documents is also a valuable addition. The code is now well-documented, and the architectural changes are clearly explained. Overall, this is an excellent set of improvements with no outstanding issues found in the changes.

[Copilot]

Pull request overview

This pull request is a comprehensive documentation and code organization cleanup for the Jet LLVM-based EVM JIT compiler. It adds extensive rustdoc comments throughout the codebase, creates new developer guides, updates architecture documentation to reflect recent refactorings (removal of runtime-ir/jet.ll, introduction of RuntimeBuilder), and improves API design by making internal modules private while maintaining clean public interfaces.

Changes:

• Added comprehensive rustdoc documentation with examples to all public APIs in jet, jet_runtime, and jet_ir crates
• Created new documentation: docs/test_coverage.md (opcode testing status) and docs/process/new-runtime-function.md (developer guide)
• Updated docs/architecture/architecture.md to document the four-crate structure, RuntimeBuilder pattern, and resolved historical issues
• Improved API design by making binding, constants, and types modules private with public re-exports
• Completely rewrote README.md with badges, clearer structure, and better onboarding information

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/test_coverage.md	New comprehensive test coverage documentation with opcode status table and test framework guide
docs/process/new-runtime-function.md	New step-by-step guide for adding runtime functions
docs/architecture/philosophy.md	Minor title and footer text updates
docs/architecture/architecture.md	Major update documenting RuntimeBuilder, four-crate architecture, resolved issues, and current status
crates/jet_runtime/src/lib.rs	Added crate-level docs and made binding module private
crates/jet_runtime/src/exec.rs	Added comprehensive rustdoc comments for all types and methods
crates/jet_runtime/src/error.rs	Added doc comment for Result type alias
crates/jet_ir/src/types.rs	Added field documentation for all Types struct fields
crates/jet_ir/src/lib.rs	Made constants and types modules private with public re-exports
crates/jet_ir/src/constants.rs	Added detailed doc comments for all constants
crates/jet/src/lib.rs	Added crate-level documentation
crates/jet/src/instructions.rs	Added comprehensive documentation with doctests
crates/jet/src/engine/mod.rs	Added documentation for Engine and Error types
crates/jet/src/builder/mod.rs	Added documentation for error types
crates/jet/src/builder/manager.rs	Added documentation for Manager and its methods
crates/jet/src/builder/env.rs	Added documentation for Options, Mode, and Env types
README.md	Complete rewrite with badges, architecture overview, and better getting started section

[tcrypt25519]

@copilot open a new pull request to apply changes based on the comments in this thread

[Copilot]

@tcrypt25519 I've opened a new pull request, #83, to work on those changes. Once the pull request is ready, I'll request review from you.