🔎 lintspec

lintspec screenshot

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.

Note: the main branch can contain unreleased changes. To view the README information for the latest stable release, visit crates.io or select the latest git tag from the branch/tag dropdown.

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!

Legacy slang Backend

Although the default parser backend is now the very fast solar, the legacy slang parser is still available when installing with cargo install.

cargo install lintspec --no-default-features -F slang

This feature exposes an additional CLI flag --skip-version-detection which can help if slang doesn't support the version of Solidity you target. Note that enabling slang makes the program ~7x slower compared to the default.

Usage

Usage: lintspec [OPTIONS] [PATH]... [COMMAND]
Commands:
 init Create a `.lintspec.toml` config file with default values
 completions Generate shell completion scripts
 help Print this message or the help of the given subcommand(s)
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)
 --config <CONFIG> Optional path to a TOML config file
 -o, --out <OUT> Write output to a file instead of stderr
 --inheritdoc Enforce that all public and external items have `@inheritdoc`
 --inheritdoc-override Enforce that `override` internal functions and modifiers have `@inheritdoc`
 --notice-or-dev Do not distinguish between `@notice` and `@dev` when considering "required" validation rules
 -n, --parallel <THREADS> Number of parallel workers/threads, or 0 to use the number of logical cores
 --title-ignored <TYPE> Ignore `@title` for these items (can be used more than once)
 --title-required <TYPE> Enforce `@title` for these items (can be used more than once)
 --title-forbidden <TYPE> Forbid `@title` for these items (can be used more than once)
 --author-ignored <TYPE> Ignore `@author` for these items (can be used more than once)
 --author-required <TYPE> Enforce `@author` for these items (can be used more than once)
 --author-forbidden <TYPE> Forbid `@author` for these items (can be used more than once)
 --notice-ignored <TYPE> Ignore `@notice` for these items (can be used more than once)
 --notice-required <TYPE> Enforce `@notice` for these items (can be used more than once)
 --notice-forbidden <TYPE> Forbid `@notice` for these items (can be used more than once)
 --dev-ignored <TYPE> Ignore `@dev` for these items (can be used more than once)
 --dev-required <TYPE> Enforce `@dev` for these items (can be used more than once)
 --dev-forbidden <TYPE> Forbid `@dev` for these items (can be used more than once)
 --param-ignored <TYPE> Ignore `@param` for these items (can be used more than once)
 --param-required <TYPE> Enforce `@param` for these items (can be used more than once)
 --param-forbidden <TYPE> Forbid `@param` for these items (can be used more than once)
 --return-ignored <TYPE> Ignore `@return` for these items (can be used more than once)
 --return-required <TYPE> Enforce `@return` for these items (can be used more than once)
 --return-forbidden <TYPE> Forbid `@return` for these items (can be used more than once)
 --json Output diagnostics in JSON format
 --compact Compact output
 --sort Sort the results by file path
 -s, --stdout Write diagnostics to stdout instead of stderr
 -0, --exit-zero Exit with code 0 even when there are diagnostics
 -h, --help Print help (see more with '--help')
 -V, --version Print version

Configuration

Config File

Create a default configuration with the following command:

lintspec init

This will create a .lintspec.toml file with the default configuration in the current directory. Check out the example file for more information.

All items for which the default configuration suits you can be removed from the file if desired. Note that some settings could change their default value in the future (in a new major release) which could alter behavior if they are not specified.

Environment Variables

Environment variables (in capitals, with the LS_ prefix) can also be used and take precedence over the configuration file. They use the same names as in the TOML config file and use the _ character as delimiter for nested items. An additional LS_CONFIG_PATH variable is available to set an optional path to the TOML file (the default is ./.lintspec.toml).

Examples:

• LS_CONFIG_PATH=.config/lintspec.toml
• LS_LINTSPEC_PATHS=[src,test]
• LS_LINTSPEC_INHERITDOC=false
• LS_LINTSPEC_NOTICE_OR_DEV=true: if the setting name contains _, it is not considered a delimiter
• LS_OUTPUT_JSON=true
• LS_CONSTRUCTOR_NOTICE=required

CLI Arguments

Finally, the tool can be customized with command-line arguments, which take precedence over the other two methods. To see the CLI usage information, run:

lintspec help

For arguments (--[TYPE]--required, --[TYPE]--ignored, --[TYPE]--forbidden) which expect an "item", the following values are available:

# for @title and @author
contract, interface, library
# for others
contract, interface, library, constructor, enum,
error, event,private-function, internal-function,
public-function, external-function, modifier, struct,
private-variable, internal-variable, public-variable

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

Example Workflow

name:Lintspecon:pull_request:jobs:lintspec:runs-on:ubuntu-lateststeps:- uses:actions/checkout@v2- uses:beeb/lintspec@v0.12.2# all the lines below are optionalwith:working-directory:"./"paths:"[]"exclude:"[]"extra-args:""version:"latest"fail-on-problem:"true"

Usage as a Library

The core functionality is available as a separate crate lintspec-core, which contains the parsing and validation logic without CLI dependencies.

cargo add lintspec-core

Alternatively, in Cargo.toml:

[dependencies]
lintspec-core = "0.12.2"

Feature flags

• solar: enables the solar_parse parser backend (default)
• slang: enables the slang_solidity parser backend

Credits

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

Comparison with natspec-smells

Benchmark

On a regular laptop with 16 cores, linting the Uniswap/v4-core src folder on linux, lintspec v0.11.3 is about 1700x faster, or 0.06% of the execution time:

Benchmark 1: npx @defi-wonderland/natspec-smells --include 'src/**/*.sol' --enforceInheritdoc --constructorNatspec
 Time (mean ± σ): 12.445 s ± 0.204 s [User: 14.510 s, System: 0.461 s]
 Range (min ... max): 12.238 s ... 12.824 s 10 runs
Benchmark 2: lintspec src --compact --param-required struct
 Time (mean ± σ): 7.3 ms ± 0.9 ms [User: 16.6 ms, System: 7.7 ms]
 Range (min ... max): 5.5 ms ... 10.3 ms 292 runs
Summary
 lintspec src --compact --param-required struct ran
 1708.61 ± 218.10 times faster than npx @defi-wonderland/natspec-smells --include 'src/**/*.sol' --enforceInheritdoc --constructorNatspec

Features