🔎 lintspec

Lintspec is a command-line utility (linter) that checks the completeness and validity of NatSpec doc-comments in Solidity code. It is focused on speed and ergonomics. By default, lintspec will respect gitignore rules when looking for Solidity source files.

Dual-licensed under MIT or Apache 2.0.

Installation

Via cargo

cargo install lintspec

Via cargo-binstall

cargo binstall lintspec

Via nix

nix-env -iA nixpkgs.lintspec
# or
nix-shell -p lintspec
# or
nix run nixpkgs#lintspec

Pre-built binaries and install script

Head over to the releases page!

Usage

Usage: lintspec [OPTIONS] [PATH]...

Arguments:
  [PATH]...  One or more paths to files and folders to analyze

Options:
  -e, --exclude <EXCLUDE>  Path to a file or folder to exclude (can be used more than once)
  -o, --out <OUT>          Write output to a file instead of stderr
      --inheritdoc         Enforce that all public and external items have `@inheritdoc`
      --constructor        Enforce that constructors have NatSpec
      --struct-params      Enforce that structs have `@param` for each member
      --enum-params        Enforce that enums have `@param` for each variant
  -f, --enforce <TYPE>     Enforce NatSpec on items even if they don't have params/returns/members (can be used more than once)
                           [possible values: constructor, enum, error, event, function, modifier, struct, variable]
      --enforce-all        Enforce NatSpec for all item types, even if they don't have params/returns/members
      --json               Output diagnostics in JSON format
      --compact            Compact output
      --sort               Sort the results by file path
  -h, --help               Print help (see more with '--help')
  -V, --version            Print version

Configuration

The tool can be configured with a .lintspec.toml file (see example), environment variables (see example) or CLI arguments (see above). CLI arguments take precedence over environment variables, which take precedence over the config file.

Usage in GitHub Actions

You can check your code in CI with the lintspec GitHub Action. Any .lintspec.toml or .nsignore file in the repository's root will be used to configure the execution.

The action generates annotations that are displayed in the source files when viewed (e.g. in a PR's "Files" tab).

Options

The following options are available for the action (all are optional if a config file is present):

Input	Default Value	Description	Example
working-directory	"./"	Working directory path	"./src"
paths	"[]"	Paths to scan, relative to the working directory, in square brackets and separated by commas. Required unless a .lintspec.toml file is present in the working directory.	"[path/to/file.sol,test/test.sol]"
exclude	"[]"	Paths to exclude, relative to the working directory, in square brackets and separated by commas	"[path/to/exclude,other/path.sol]"
extra-args		Extra arguments passed to the lintspec command	"--constructor=true"
version	"latest"	Version of lintspec to use. For enhanced security, you can pin this to a fixed version	"0.1.5"
fail-on-problem	"true"	Whether the action should fail when NatSpec problems have been found. Disabling this only creates annotations for found problems, but succeeds	"false"

Example Workflow

name: Lintspec

on:
  pull_request:

jobs:
  lintspec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: beeb/lintspec@main
        # all the lines below are optional
        with:
          working-directory: "./"
          paths: "[]"
          exclude: "[]"
          extra-args: ""
          version: "latest"
          fail-on-problem: "true"

Credits

This tool walks in the footsteps of natspec-smells, thanks to them for inspiring this project!

Comparison with natspec-smells

Benchmark

On an AMD Ryzen 9 7950X processor with 64GB of RAM, linting the Uniswap/v4-core src folder on WSL2 (Ubuntu), lintspec is about 214x faster, or 0.46% of the execution time:

Benchmark 1: npx @defi-wonderland/natspec-smells --include "src/**/*.sol"
  Time (mean ± σ):     12.484 s ±  0.157 s    [User: 13.581 s, System: 0.594 s]
  Range (min … max):   12.288 s … 12.817 s    10 runs

  Warning: Ignoring non-zero exit code.

Benchmark 2: lintspec src --compact=true
  Time (mean ± σ):      58.2 ms ±   1.3 ms    [User: 264.0 ms, System: 67.9 ms]
  Range (min … max):    53.9 ms …  61.3 ms    50 runs

  Warning: Ignoring non-zero exit code.

Summary
  lintspec src --compact=true ran
  214.55 ± 5.61 times faster than npx @defi-wonderland/natspec-smells --include "src/**/*.sol"

Features

Feature	lintspec	natspec-smells
Identify missing NatSpec	✅	✅
Identify duplicate NatSpec	✅	✅
Include files/folders	✅	✅
Exclude files/folders	✅	✅
Enforce usage of @inheritdoc	✅	✅
Enforce NatSpec on constructors	✅	✅
Configure via config file	✅	✅
Configure via env variables	✅	❌
Respects gitignore files	✅	❌
Enforce NatSpec on enums	✅	❌
Pretty output with code excerpt	✅	❌
JSON output	✅	❌
Output to file	✅	❌
Multithreaded	✅	❌
No pre-requisites (node/npm)	✅	❌