Dargon789/forge master

[Dargon789]

Motivation

Solution

PR Checklist

• Added Tests
• Added Documentation
• Breaking changes

Summary by Sourcery

Add enum variant table support in documentation, refine provider selection logic, standardize comparison methods, update dependencies and tooling, and introduce a sample Counter example with its tests, scripts, and CI workflows.

New Features:

• Add try_write_variant_table to render enum variant documentation tables
• Introduce a Counter Solidity example with contracts, tests, script, and a project README

Bug Fixes:

• Add missing semicolons and normalize return Ok(()) calls
• Clarify RestrictionsError message formatting in compilation settings

Enhancements:

• Simplify VerificationProvider client logic to use direct enum matching and remove helper methods
• Replace total_cmp with partial_cmp (with fallback) across sorting and comparison utilities
• Update derive_more dependency to v1.0 and downgrade Python setup action version

CI:

• Add multiple new GitHub workflows (nextest, CodeQL, Jekyll Pages deployment, APIsec, Docker image CI, CircleCI)
• Update Python setup action from v5 to v4 and adjust Forge RPC cache step

Documentation:

• Add README documentation for the Counter example project

Tests:

• Adjust redaction patterns in test-utils to expect ETH token symbol

Chores:

• Implement From<Vec> for Comments type

[sourcery-ai]

Reviewer's Guide

This PR enriches the documentation pipeline by adding variant‐table support, refactors provider‐selection and sorting routines to use more robust pattern and comparison methods, applies a minor regex fix for test redactions, adds missing comment‐conversion helpers, bumps a dependency, and layers in comprehensive CI scaffolding—including multiple GitHub workflows, issue templates, and a new “counter” example project.

Entity relationship diagram for Counter contract storage

erDiagram
    COUNTER {
        uint256 number
    }

Loading

Class diagram for new and updated documentation writer types

classDiagram
    class BufWriter {
        +try_write_variant_table(params: EnumDefinition, comments: Comments)
        +try_write_properties_table(params, comments)
        +try_write_events_table(params, comments)
    }
    class Comments {
        +From<Vec<Comment>>
    }
    class EnumDefinition {
        values
    }
    class Comment {
        tag
        match_first_word(name)
    }
    BufWriter --> EnumDefinition
    BufWriter --> Comments
    Comments <|-- Comment
    EnumDefinition "1" -- "*" Comment : values

Loading

Class diagram for Counter Solidity contract

classDiagram
    class Counter {
        +number: uint256
        +setNumber(newNumber: uint256)
        +increment()
    }

Loading

Class diagram for CounterScript Solidity contract

classDiagram
    class CounterScript {
        +counter: Counter
        +setUp()
        +run()
    }
    CounterScript --> Counter

Loading

File-Level Changes

Change	Details	Files
Add variant table rendering in documentation	Define VARIANTS_TABLE_HEADERS and separator Implement try_write_variant_table in BufWriter Invoke try_write_variant_table after writing enum sections	crates/doc/src/writer/buf_writer.rs crates/doc/src/writer/as_doc.rs
Refactor VerificationProviderType to use matches! macros and simplify key checks	Replace is_sourcify/is_etherscan calls with matches! Always use Sourcify when specified and enforce API key only for Etherscan Remove helper methods and redundant key existence checks	crates/verify/src/provider.rs
Standardize comparisons to use partial_cmp with unwrap fallback	Swap total_cmp for partial_cmp(...).unwrap_or(Ordering::Equal) in snapshot sorting and pct formatting Apply same pattern in suggestions and contract matching	crates/forge/src/cmd/snapshot.rs crates/cli/src/utils/suggestions.rs crates/common/src/contracts.rs
Adjust test redactions to expect ETH symbol	Update regex in test-utils to match “ETH” only	crates/test-utils/src/util.rs
Add missing Comments conversion helper and minor syntax fixes	Implement From<Vec> for Comments Add missing semicolons on return statements in comment parser	crates/doc/src/parser/comment.rs
Bump dependency and add CI/workflow scaffolding with example project	Downgrade derive_more to 1.0 Update actions/setup-python to v4 and pip install Add CodeQL, Jekyll, Docker, APIsec, and CircleCI configs Introduce GitHub issue templates (bug, feature, custom) Include a new “counter” example with source, test, script, README, and foundry.toml	Cargo.toml .github/workflows/nextest.yml .github/workflows/codeql.yml .github/workflows/jekyll.yml counter/.github/workflows/test.yml .github/workflows/docker-image.yml .github/ISSUE_TEMPLATE/bug_report.md .github/ISSUE_TEMPLATE/feature_request.md .github/ISSUE_TEMPLATE/custom.md .circleci/config.yml .github/workflows/apisec-scan.yml .deps/remix-tests/remix_tests.sol .deps/remix-tests/remix_accounts.sol counter/README.md counter/test/Counter.t.sol counter/script/Counter.s.sol counter/src/Counter.sol counter/foundry.toml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[gemini-code-assist]

Summary of Changes

Hello @Dargon789, 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 significantly expands the project's infrastructure by integrating a new Foundry-based smart contract development environment, complete with CI/CD pipelines and essential Solidity testing utilities. Concurrently, it refines several core Rust components, enhancing dependency management, improving documentation generation for Solidity enums, and streamlining the user experience for script simulations and verification provider selection.

Highlights

• New Foundry Project Setup: A new Foundry project named 'counter' has been added, including a basic Solidity Counter contract, its deployment script, and tests. This setup also comes with a dedicated .gitignore, README.md, and foundry.toml configuration.
• CI/CD and Development Environment Configuration: New configurations for continuous integration and development environments have been introduced. This includes a basic .circleci/config.yml, an empty .codesandbox/tasks.json, and a GitHub Actions workflow (counter/.github/workflows/test.yml) for automated build, test, and format checks for the Foundry project.
• Solidity Testing Utilities: New Solidity libraries for Remix tests, remix_accounts.sol and remix_tests.sol, have been added under .deps/remix-tests/. These provide common test accounts and assertion functions for Solidity smart contract testing.
• GitHub Issue Templates: Standardized GitHub issue templates for bug reports, feature requests, and a custom template have been added to the .github/ISSUE_TEMPLATE/ directory to streamline issue management.
• Rust Dependency Updates and Refinements: Several Rust dependencies in Cargo.lock and Cargo.toml have been updated or had their versioning constraints relaxed. Notable changes include updates to ammonia, html5ever, nu-ansi-term, and tracing-subscriber, along with adjustments to regex-automata, regex-syntax, and derive_more versions.
• Refactored Comparison Logic: Internal utility functions in crates/cli/src/utils/suggestions.rs, crates/common/src/contracts.rs, and crates/forge/src/cmd/snapshot.rs have been updated to use partial_cmp instead of total_cmp for floating-point comparisons, improving robustness.
• Enhanced Enum Documentation Generation: The documentation generation process for enums has been improved in crates/doc/src/writer/as_doc.rs and crates/doc/src/writer/buf_writer.rs. It now filters specific comment tags and includes a dedicated table for enum variants, providing clearer documentation.
• Simplified Script Simulation Output: The script simulation output in crates/script/src/simulate.rs and crates/test-utils/src/util.rs has been simplified by removing chain-specific token symbol logic, defaulting to 'ETH' for estimated amounts, and updating corresponding regex patterns.
• Streamlined Verification Provider Selection: The logic for selecting verification providers in crates/verify/src/provider.rs has been refactored for clarity and robustness, removing redundant helper methods and simplifying conditional checks for Etherscan and Sourcify.

Ignored Files

• Ignored by pattern: .github/workflows/** (5)
  • .github/workflows/apisec-scan.yml
  • .github/workflows/codeql.yml
  • .github/workflows/docker-image.yml
  • .github/workflows/jekyll.yml
  • .github/workflows/nextest.yml

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

[sourcery-ai]

Hey there - I've reviewed your changes - here's some feedback:

• This PR mixes several unrelated changes (documentation rendering, provider logic, CI workflows, example contracts), consider splitting it into smaller, focused PRs for easier review and better traceability.
• The new variant table rendering shares a lot of logic with the existing parameter/events tables; you could extract a common helper to reduce duplication and ensure consistency.
• Hardcoding the token symbol to "ETH" may break simulations on non‐Ethereum chains—consider using the existing chain metadata or allowing configuration to support other native tokens.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- This PR mixes several unrelated changes (documentation rendering, provider logic, CI workflows, example contracts), consider splitting it into smaller, focused PRs for easier review and better traceability.
- The new variant table rendering shares a lot of logic with the existing parameter/events tables; you could extract a common helper to reduce duplication and ensure consistency.
- Hardcoding the token symbol to "ETH" may break simulations on non‐Ethereum chains—consider using the existing chain metadata or allowing configuration to support other native tokens.

## Individual Comments

### Comment 1
<location> `crates/doc/src/writer/buf_writer.rs:187` </location>
<code_context>
         self.try_write_table(CommentTag::Param, params, comments, "Properties")
     }

+    /// Tries to write the variant table to the buffer.
+    /// Doesn't write anything if either params or comments are empty.
+    pub fn try_write_variant_table(
</code_context>

<issue_to_address>
**issue (complexity):** Consider extracting a generic helper to handle table writing and reduce duplicated boilerplate code.

Here’s one way to remove almost all of the duplication by extracting a small, generic `try_write_table_rows` helper.  You keep all existing behavior (including your custom tag‐filtering), but collapse the “write title, headers, separator, rows, blank line” boilerplate into one place:

```rust
impl DocWriter {
    /// Generic table writer: filters by `tag`, writes a bold `title`,
    /// pipes the headers/separator, then calls `row_fn` for each item.
    fn try_write_table_rows<T, F>(
        &mut self,
        tag: CommentTag,
        items: impl IntoIterator<Item = T>,
        comments: &Comments,
        title: &str,
        headers: &[&str],
        mut row_fn: F,
    ) -> fmt::Result
    where
        F: FnMut(&T, &Comments, &mut Self) -> fmt::Result,
    {
        let comments = comments.include_tags(&[tag]);
        if comments.is_empty() {
            return Ok(());
        }
        self.write_bold(title)?;
        self.writeln()?;
        self.write_piped(&headers.join("|"))?;
        // simple separator of same length as headers
        let sep = headers.iter().map(|_| "---").join("|");
        self.write_piped(&sep)?;
        for item in items {
            row_fn(&item, &comments, self)?;
        }
        self.writeln()?;
        Ok(())
    }

    pub fn try_write_variant_table(
        &mut self,
        params: &EnumDefinition,
        comments: &Comments,
    ) -> fmt::Result {
        self.try_write_table_rows(
            // include both Param and custom “variant” tags
            CommentTag::Custom("variant".into()),
            &params.values,
            comments,
            "Variants",
            &VARIANTS_TABLE_HEADERS,
            |value, comments, w| {
                let name = value.as_ref().map(|v| v.name.clone());
                let text = name
                    .as_ref()
                    .and_then(|n| comments.iter().find_map(|c| c.match_first_word(n)))
                    .unwrap_or_default()
                    .replace('\n', " ");
                let row = [
                    Markdown::Code(name.as_deref().unwrap_or("<none>")).as_doc()?,
                    text,
                ];
                w.write_piped(&row.join("|"))?;
                Ok(())
            },
        )
    }
}
```

Benefits:
- All table‐boilerplate lives in one short method.
- You only pass headers + a tiny row lambda.
- Keeps your custom tag filtering and Markdown code exactly the same.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request introduces several enhancements, including support for enum variant tables in documentation, refactoring of provider selection logic, and standardization of float comparisons. It also adds a new counter example project with full CI setup.

My review focuses on a few key areas. I've identified a regression where the native currency symbol is hardcoded to 'ETH' in script simulation outputs, which affects multi-chain support. I've also noted a minor formatting issue in a new Solidity dependency file.

Overall, the changes are a good step forward, especially the documentation improvements and refactorings. Addressing the currency symbol issue is important for maintaining the tool's multi-chain capabilities.