ScopeLint

A simple and opinionated tool designed for basic formatting/linting of Solidity and TOML code in foundry projects.

• ScopeLint
  • Installation
  • Usage
    • scopelint fmt
    • scopelint check
    • scopelint fix
    • scopelint spec
  • Development

Installation

When using the ScopeLift Foundry template scopelint will automatically be ran in CI. To run locally:

1. Install the rust toolchain
2. Run cargo install scopelint

Usage

Once installed there are four commands:

• scopelint fmt
• scopelint check
• scopelint fix
• scopelint spec

For all commands, please open issues for any bug reports, suggestions, or feature requests.

scopelint fmt

This command will format:

• Solidity files using the configuration specified in foundry.toml.
• TOML files using a hardcoded configuration that indents keys and sorts them alphabetically to improve readability.

Flags:

• --check: Show changes without modifying files (dry run mode)

scopelint check

This command ensures that development best practices are consistently followed by validating that:

• Test names follow a convention of ^test(Fork)?(Fuzz)?(_Revert(If|When|On))?_(\w+)*$. (To see a list of example valid test names, see here).
• Constants and immutables are in ALL_CAPS.
• Function names and visibility in forge scripts only have 1 public run method per script.
• Internal or private functions in the source directory start with a leading underscore.

Path configuration: scopelint check (and scopelint spec) use your existing Foundry paths so they work with non-default layouts (e.g. contracts/ instead of src/). Paths are read from foundry.toml in the same way as Forge:

• If present, [profile.default] (or root-level) src, test, and script are used.

• You can override them for scopelint only with an optional [check] section:

  [profile.default]
  src = "contracts"
  test = "test"
  script = "script"
  
  # Optional: scopelint-specific path overrides (defaults to profile.default if omitted)
  [check]
  src_path = "./contracts"
  script_path = "./script"
  test_path = "./test"

  If [check] is omitted, Foundry’s paths are used as-is, so no re-definition is required.

More checks are planned for the future.

Scopelint is opinionated in that it does not let you disable rules globally. However, you can ignore specific rules for specific files using:

1. Inline comments in your Solidity files:

   // scopelint: ignore-src-file  // Ignore 'src' rule for entire file
   // scopelint: ignore-error-next-line  // Ignore 'error' rule for next line

2. .scopelint config file in your project root:

   # Ignore entire files
   [ignore]
   files = [
       "src/legacy/old.sol",
       "test/integration/*.sol"
   ]
   
   # Ignore specific rules for specific files
   [ignore.overrides]
   "src/BaseBridgeReceiver.sol" = ["src"]  # Only ignore 'src' rule
   "src/legacy/**/*.sol" = ["src", "error"]  # Ignore multiple rules

   Supported rules: error, import, variable, constant, test, script, src, eip712

scopelint fix

Applies safe, automatic fixes and then runs scopelint check. Currently supports:

• Unused imports: Removes unused symbols from named imports (import { A, B } from "...") and removes entire aliased import lines (import "..." as Alias) when the alias is unused.

Only findings that are not ignored (via inline comments or .scopelint) are fixed. After fixing, any remaining convention or formatting issues are reported as with scopelint check.

scopelint spec

Most developers don't have formal specifications they are building towards, and instead only have a general idea of what they want their contracts to do. As a result, documentation and tests are the closest things many protocols have to a specification (unless they go through the formal verification process). And because documentation is often not written until the end of the development process, it is often incomplete or inaccurate, and therefore tests are typically the closest thing to a specification.

scopelint spec embraces this philosophy of "your tests are your spec" to help developers come up with a spec with minimal effort—structure your tests contracts and test names and described in the Best Practices guide, and scopelint spec will generate a specification for you! This specification can be shared with other stakeholders to make sure everyone is on the same page about what the contract should do.

Below is a simple example for an ERC-20 token, the full example repo can be found here.

Flags:

• --show-internal: Include internal and private functions in the specification (by default, only public and external functions are shown)

Currently this feature is in beta, and we are looking for feedback on how to improve it. Right now it's focused on specifications for unit tests, which are very useful for developers but less useful for higher-level stakeholders. As a result, it does not yet include information about protocol invariants or integration test / user-story types of specifications. If you have any thoughts or ideas, please open an issue here.

Development

For developers interested in contributing to scopelint, please see our Development Guide for detailed information about:

• Setting up the development environment
• Project structure and architecture
• Adding new validators and features
• Testing and code quality standards
• Contributing guidelines