Static analysis for Foundry projects

Opinionated linting for Solidity and TOML.

ScopeLint is a simple and opinionated tool designed for basic formatting and linting of Solidity and TOML code in Foundry projects. It runs as a lightweight CLI that formats your project and enforces naming and layout conventions so tests, scripts, and specs stay clean as your codebase grows.

Get started View on GitHub

Works with existing foundry.toml layouts. No custom config required.

Why ScopeLint?

Foundry gives you great primitives, but it is still easy for projects to drift into inconsistent naming, test layouts, and scripts that are hard to reason about. ScopeLint keeps the basics sharp so you can focus on protocol logic.

Solidity-aware checks

ScopeLint understands common patterns in Foundry projects: tests, scripts, and sources. Rules are tailored to Solidity codebases instead of generic linting heuristics.

Conventions over config

No giant rule matrices. ScopeLint encodes a small set of opinionated practices—like test naming and internal function prefixes—so teams can converge on a shared style quickly.

Fits your workflow

Run it locally via the CLI or wire it into CI. It uses the same paths and profiles as Forge by reading your existing foundry.toml.

Key capabilities

scopelint fmt

Formats Solidity files using your Foundry configuration and pretty‑prints TOML with indented, alphabetically sorted keys for better readability.

scopelint check

Validates test naming, constants, script entrypoints, internal function prefixes, and more to ensure best practices are applied consistently across the project.

scopelint fix

Applies safe automatic fixes, like removing unused imports, and then runs scopelint check so you see what still needs attention.

scopelint spec

Treats your tests as the spec for your contracts. Generates a human‑readable specification based on your test layout and naming, so stakeholders can quickly grasp intended behavior.

Install & basic usage

Install with Cargo

  1. Install the Rust toolchain if you don’t have it yet.
  2. Install ScopeLint from crates.io:
cargo install scopelint

Once installed, you can run it from the root of your Foundry project. It reads foundry.toml paths the same way Forge does.

Run the commands

# Format Solidity and TOML
scopelint fmt

# Check conventions and report findings
scopelint check

# Apply safe automatic fixes, then re-check
scopelint fix

# Generate a human-readable specification from tests
scopelint spec

Examples of findings

ScopeLint focuses on issues that make Solidity projects harder to understand and maintain, not just stylistic nits. Here are a few example checks.

Test naming conventions

// test/Counter.t.sol

function testCounter() public { ... }     // ❌ too vague
function test_RevertIf_Zero() public { }  // ✅ matches convention

ScopeLint validates that test names follow a convention based on Foundry best practices so your test suite reads like a spec.

Constants & immutables

// src/Token.sol

uint256 maxSupply = 1_000_000;          // ❌ should be ALL_CAPS
uint256 public constant MAX_SUPPLY = 1_000_000; // ✅

Constants and immutables are expected to be in ALL_CAPS, making them easy to scan in larger contracts.

Script entrypoints

// script/Deploy.s.sol

contract Deploy is Script {
    function run() public { ... }
    function runGoerli() public { ... } // ❌ only one public run allowed
}

Forge scripts should expose a single public run entrypoint. ScopeLint flags scripts that define more than one.

CI & workflow integration

ScopeLint is just a CLI, so it drops cleanly into any CI system that can run a few shell commands. A typical GitHub Actions workflow installs the Rust toolchain, installs ScopeLint, and runs checks against your Foundry project.

You can also use it in pre‑commit hooks or as part of a local formatting script to keep branches clean before they ever reach CI.

GitHub Actions example

name: scopelint

on:
  push:
    branches: [main]
  pull_request:

jobs:
  scopelint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - name: Install ScopeLint
        run: cargo install scopelint
      - name: Run ScopeLint
        run: |
          scopelint fmt --check
          scopelint check

FAQ

What is ScopeLint?

ScopeLint is a small, opinionated command-line tool for formatting and linting Solidity and TOML in Foundry projects. Install it with cargo install scopelint and run scopelint fmt, scopelint check, or scopelint fix from the root of your project.

What does ScopeLint check for?

ScopeLint focuses on a small set of high‑leverage rules: conventions for test names, constants, script entrypoints, internal/private function prefixes, unused imports, and certain project layout patterns. More rules are planned over time.

Does it modify my files?

scopelint check is read‑only and only reports findings. scopelint fmt and scopelint fix will modify files, but only in ways designed to be safe and predictable (formatting and specific automated fixes).

How does it find my source, test, and script paths?

ScopeLint reads foundry.toml the same way Forge does. It uses [profile.default] (or root-level) src, test, and script settings, with optional overrides via an extra [check] section.

Can I ignore specific rules or files?

Yes. You can add inline // scopelint: ... comments in Solidity files or configure a .scopelint file in your project root to ignore specific files or rules. See the GitHub README for concrete examples.

Where can I ask questions or request new checks?

Open an issue on the GitHub repository with as much context as you can share. Real‑world examples are especially helpful.