{"id":25952663,"url":"https://github.com/beeb/lintspec","last_synced_at":"2026-02-15T16:12:03.105Z","repository":{"id":277713471,"uuid":"932742585","full_name":"beeb/lintspec","owner":"beeb","description":"A blazingly fast linter for NatSpec comments in Solidity code","archived":false,"fork":false,"pushed_at":"2025-03-01T23:15:00.000Z","size":434,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-02T00:20:16.782Z","etag":null,"topics":["checker","docstrings","documentation","linter","natspec","solidity"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beeb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-14T12:44:21.000Z","updated_at":"2025-03-01T23:14:00.000Z","dependencies_parsed_at":"2025-02-15T16:28:52.145Z","dependency_job_id":"f38b8263-3820-4b36-9a46-d5238eeb838e","html_url":"https://github.com/beeb/lintspec","commit_stats":null,"previous_names":["beeb/lintspec"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeb%2Flintspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeb%2Flintspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeb%2Flintspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeb%2Flintspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beeb","download_url":"https://codeload.github.com/beeb/lintspec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241868345,"owners_count":20033822,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["checker","docstrings","documentation","linter","natspec","solidity"],"created_at":"2025-03-04T14:53:34.811Z","updated_at":"2026-02-11T19:04:01.582Z","avatar_url":"https://github.com/beeb.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔎 lintspec\n\n![lintspec screenshot](https://raw.githubusercontent.com/beeb/lintspec/refs/heads/main/screenshot.png)\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/beeb/lintspec\"\u003e\u003cimg\n      alt=\"github\"\n      src=\"https://img.shields.io/badge/github-beeb%2Flintspec-228b22?style=flat\u0026logo=github\"\n      height=\"20\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/lintspec\"\u003e\u003cimg\n      alt=\"crates.io\"\n      src=\"https://img.shields.io/crates/v/lintspec.svg?style=flat\u0026color=e37602\u0026logo=rust\"\n      height=\"20\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.rs/lintspec/latest/lintspec/\"\u003e\u003cimg\n      alt=\"docs.rs\"\n      src=\"https://img.shields.io/badge/docs.rs-lintspec-3b74d1?style=flat\u0026labelColor=555555\u0026logo=docs.rs\"\n      height=\"20\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.rs/lintspec/latest/lintspec/\"\u003e\u003cimg\n      alt=\"MSRV\"\n      src=\"https://img.shields.io/badge/MSRV-1.89.0-b83fbf?style=flat\u0026labelColor=555555\u0026logo=docs.rs\"\n      height=\"20\"\n  /\u003e\u003c/a\u003e\n  \u003ca href=\"https://codspeed.io/beeb/lintspec\"\u003e\u003cimg\n      alt=\"CodSpeed\"\n      src=\"https://img.shields.io/endpoint?url=https://codspeed.io/badge.json\"\n  /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\nLintspec is a command-line utility (linter) that checks the completeness and validity of\n[NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) doc-comments in Solidity code. It is focused on\nspeed and ergonomics. By default, lintspec will respect gitignore rules when looking for Solidity source files.\n\nDual-licensed under MIT or Apache 2.0.\n\n\u003e Note: the `main` branch can contain unreleased changes. To view the README information for the latest stable release,\n\u003e visit [crates.io](https://crates.io/crates/lintspec) or select the latest git tag from the branch/tag dropdown.\n\n## Installation\n\n#### Via `cargo`\n\n```bash\ncargo install lintspec\n```\n\n#### Via [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall)\n\n```bash\ncargo binstall lintspec\n```\n\n#### Via `nix`\n\n```bash\nnix-env -iA nixpkgs.lintspec\n# or\nnix-shell -p lintspec\n# or\nnix run nixpkgs#lintspec\n```\n\n#### Pre-built binaries and install script\n\nHead over to the [releases page](https://github.com/beeb/lintspec/releases)!\n\n### Legacy `slang` Backend\n\nAlthough the default parser backend is now the very fast [`solar`](https://github.com/paradigmxyz/solar), the legacy\n[`slang`](https://github.com/NomicFoundation/slang) parser is still available when installing with `cargo install`.\n\n```bash\ncargo install lintspec --no-default-features -F slang\n```\n\nThis feature exposes an additional CLI flag `--skip-version-detection` which can help if `slang` doesn't support the\nversion of Solidity you target. Note that enabling `slang` makes the program ~7x slower compared to the default.\n\n## Usage\n\n```text\nUsage: lintspec [OPTIONS] [PATH]... [COMMAND]\n\nCommands:\n  init         Create a `.lintspec.toml` config file with default values\n  completions  Generate shell completion scripts\n  help         Print this message or the help of the given subcommand(s)\n\nArguments:\n  [PATH]...  One or more paths to files and folders to analyze\n\nOptions:\n  -e, --exclude \u003cEXCLUDE\u003e        Path to a file or folder to exclude (can be used more than once)\n      --config \u003cCONFIG\u003e          Optional path to a TOML config file\n  -o, --out \u003cOUT\u003e                Write output to a file instead of stderr\n      --inheritdoc               Enforce that all public and external items have `@inheritdoc`\n      --inheritdoc-override      Enforce that `override` internal functions and modifiers have `@inheritdoc`\n      --notice-or-dev            Do not distinguish between `@notice` and `@dev` when considering \"required\" validation rules\n      --title-ignored \u003cTYPE\u003e     Ignore `@title` for these items (can be used more than once)\n      --title-required \u003cTYPE\u003e    Enforce `@title` for these items (can be used more than once)\n      --title-forbidden \u003cTYPE\u003e   Forbid `@title` for these items (can be used more than once)\n      --author-ignored \u003cTYPE\u003e    Ignore `@author` for these items (can be used more than once)\n      --author-required \u003cTYPE\u003e   Enforce `@author` for these items (can be used more than once)\n      --author-forbidden \u003cTYPE\u003e  Forbid `@author` for these items (can be used more than once)\n      --notice-ignored \u003cTYPE\u003e    Ignore `@notice` for these items (can be used more than once)\n      --notice-required \u003cTYPE\u003e   Enforce `@notice` for these items (can be used more than once)\n      --notice-forbidden \u003cTYPE\u003e  Forbid `@notice` for these items (can be used more than once)\n      --dev-ignored \u003cTYPE\u003e       Ignore `@dev` for these items (can be used more than once)\n      --dev-required \u003cTYPE\u003e      Enforce `@dev` for these items (can be used more than once)\n      --dev-forbidden \u003cTYPE\u003e     Forbid `@dev` for these items (can be used more than once)\n      --param-ignored \u003cTYPE\u003e     Ignore `@param` for these items (can be used more than once)\n      --param-required \u003cTYPE\u003e    Enforce `@param` for these items (can be used more than once)\n      --param-forbidden \u003cTYPE\u003e   Forbid `@param` for these items (can be used more than once)\n      --return-ignored \u003cTYPE\u003e    Ignore `@return` for these items (can be used more than once)\n      --return-required \u003cTYPE\u003e   Enforce `@return` for these items (can be used more than once)\n      --return-forbidden \u003cTYPE\u003e  Forbid `@return` for these items (can be used more than once)\n      --json                     Output diagnostics in JSON format\n      --compact                  Compact output\n      --sort                     Sort the results by file path\n  -h, --help                     Print help (see more with '--help')\n  -V, --version                  Print version\n```\n\n## Configuration\n\n### Config File\n\nCreate a default configuration with the following command:\n\n```bash\nlintspec init\n```\n\nThis will create a `.lintspec.toml` file with the default configuration in the current directory. Check out the\n[example file](https://github.com/beeb/lintspec/blob/main/.lintspec.toml) for more information.\n\nAll items for which the default configuration suits you can be removed from the file if desired. Note that some settings\ncould change their default value in the future (in a new major release) which could alter behavior if they are not\nspecified.\n\n### Environment Variables\n\nEnvironment variables (in capitals, with the `LS_` prefix) can also be used and take precedence over the configuration\nfile. They use the same names as in the TOML config file and use the `_` character as delimiter for nested items. An\nadditional `LS_CONFIG_PATH` variable is available to set an optional path to the TOML file (the default is\n`./.lintspec.toml`).\n\nExamples:\n\n- `LS_CONFIG_PATH=.config/lintspec.toml`\n- `LS_LINTSPEC_PATHS=[src,test]`\n- `LS_LINTSPEC_INHERITDOC=false`\n- `LS_LINTSPEC_NOTICE_OR_DEV=true`: if the setting name contains `_`, it is not considered a delimiter\n- `LS_OUTPUT_JSON=true`\n- `LS_CONSTRUCTOR_NOTICE=required`\n\n### CLI Arguments\n\nFinally, the tool can be customized with command-line arguments, which take precedence over the other two methods. To\nsee the CLI usage information, run:\n\n```bash\nlintspec help\n```\n\nFor arguments (`--[TYPE]--required`, `--[TYPE]--ignored`, `--[TYPE]--forbidden`) which expect an \"item\", the following\nvalues are available:\n\n```text\n# for @title and @author\ncontract, interface, library\n# for others\ncontract, interface, library, constructor, enum,\nerror, event,private-function, internal-function,\npublic-function, external-function, modifier, struct,\nprivate-variable, internal-variable, public-variable\n```\n\n## Usage in GitHub Actions\n\nYou can check your code in CI with the lintspec GitHub Action. Any `.lintspec.toml` or `.nsignore` file in the\nrepository's root will be used to configure the execution.\n\nThe action generates\n[annotations](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-warning-message)\nthat are displayed in the source files when viewed (e.g. in a PR's \"Files\" tab).\n\n### Options\n\nThe following options are available for the action (all are optional if a config file is present):\n\n| Input               | Default Value | Description                                                                                                                                                                | Example                              |\n| ------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |\n| `working-directory` | `\"./\"`        | Working directory path                                                                                                                                                     | `\"./src\"`                            |\n| `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]\"` |\n| `exclude`           | `\"[]\"`        | Paths to exclude, relative to the working directory, in square brackets and separated by commas                                                                            | `\"[path/to/exclude,other/path.sol]\"` |\n| `extra-args`        |               | Extra arguments passed to the `lintspec` command                                                                                                                           | `\"--inheritdoc=false\"`               |\n| `version`           | `\"latest\"`    | Version of lintspec to use. For enhanced security, you can pin this to a fixed version                                                                                     | `\"0.9.0\"`                            |\n| `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\"`                            |\n\n### Example Workflow\n\n```yaml\nname: Lintspec\n\non:\n  pull_request:\n\njobs:\n  lintspec:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v2\n      - uses: beeb/lintspec@v0.12.2\n        # all the lines below are optional\n        with:\n          working-directory: \"./\"\n          paths: \"[]\"\n          exclude: \"[]\"\n          extra-args: \"\"\n          version: \"latest\"\n          fail-on-problem: \"true\"\n```\n\n## Usage as a Library\n\nThe core functionality is available as a separate crate `lintspec-core`, which contains the parsing and validation logic\nwithout CLI dependencies.\n\n```bash\ncargo add lintspec-core\n```\n\nAlternatively, in `Cargo.toml`:\n\n```toml\n[dependencies]\nlintspec-core = \"0.12.2\"\n```\n\n### Feature flags\n\n- `solar`: enables the `solar_parse` parser backend (default)\n- `slang`: enables the `slang_solidity` parser backend\n\n## Credits\n\nThis tool walks in the footsteps of [natspec-smells](https://github.com/defi-wonderland/natspec-smells), thanks to them\nfor inspiring this project!\n\n## Comparison with natspec-smells\n\n### Benchmark\n\nOn a regular laptop with 16 cores, linting the [Uniswap/v4-core](https://github.com/Uniswap/v4-core) `src` folder on\nlinux, lintspec v0.11.3 is about 1700x faster, or 0.06% of the execution time:\n\n```text\nBenchmark 1: npx @defi-wonderland/natspec-smells --include 'src/**/*.sol' --enforceInheritdoc --constructorNatspec\n  Time (mean ± σ):     12.445 s ±  0.204 s    [User: 14.510 s, System: 0.461 s]\n  Range (min … max):   12.238 s … 12.824 s    10 runs\n\nBenchmark 2: lintspec src --compact --param-required struct\n  Time (mean ± σ):       7.3 ms ±   0.9 ms    [User: 16.6 ms, System: 7.7 ms]\n  Range (min … max):     5.5 ms …  10.3 ms    292 runs\n\nSummary\n  lintspec src --compact --param-required struct ran\n  1708.61 ± 218.10 times faster than npx @defi-wonderland/natspec-smells --include 'src/**/*.sol' --enforceInheritdoc --constructorNatspec\n```\n\n### Features\n\n| Feature                         | `lintspec` | `natspec-smells` |\n| ------------------------------- | ---------- | ---------------- |\n| Identify missing NatSpec        | ✅         | ✅               |\n| Identify duplicate NatSpec      | ✅         | ✅               |\n| Include files/folders           | ✅         | ✅               |\n| Exclude files/folders           | ✅         | ✅               |\n| Enforce usage of `@inheritdoc`  | ✅         | ✅               |\n| Enforce NatSpec on constructors | ✅         | ✅               |\n| Configure via config file       | ✅         | ✅               |\n| Configure via env variables     | ✅         | ❌               |\n| Respects gitignore files        | ✅         | ❌               |\n| Granular validation rules       | ✅         | ❌               |\n| Pretty output with code excerpt | ✅         | ❌               |\n| JSON output                     | ✅         | ❌               |\n| Output to file                  | ✅         | ❌               |\n| Multithreaded                   | ✅         | ❌               |\n| Built-in CI action              | ✅         | ❌               |\n| No pre-requisites (node/npm)    | ✅         | ❌               |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeb%2Flintspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeeb%2Flintspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeb%2Flintspec/lists"}