Merge pull request #689 from protofire/feature-use-natspec

Feature use natspec

Author: dbale-altoros

conf/rulesets/solhint-all.js

@@ -24,6 +24,31 @@ module.exports = Object.freeze({
         maxLength: 32,
       },
     ],
+    'use-natspec': [
+      'warn',
+      {
+        title: {
+          enabled: true,
+          ignore: {},
+        },
+        author: {
+          enabled: true,
+          ignore: {},
+        },
+        notice: {
+          enabled: true,
+          ignore: {},
+        },
+        param: {
+          enabled: true,
+          ignore: {},
+        },
+        return: {
+          enabled: true,
+          ignore: {},
+        },
+      },
+    ],
     'constructor-syntax': 'warn',
     'gas-calldata-parameters': 'warn',
     'gas-custom-errors': 'warn',

docs/rules.md

@@ -21,6 +21,7 @@ title:       "Rule Index of Solhint"
 | [one-contract-per-file](./rules/best-practices/one-contract-per-file.md) | Enforces the use of ONE Contract per file see [here](https://docs.soliditylang.org/en/v0.8.21/style-guide.html#contract-and-library-names) | $~~~~~~~~$✔️ |            |
 | [payable-fallback](./rules/best-practices/payable-fallback.md)           | When fallback is not payable and there is no receive function you will not be able to receive currency.                                    | $~~~~~~~~$✔️ |            |
 | [reason-string](./rules/best-practices/reason-string.md)                 | Require or revert statement must have a reason string and check that each reason string is at most N characters long.                      | $~~~~~~~~$✔️ |            |
+| [use-natspec](./rules/best-practices/use-natspec.md)                     | Enforces the presence and correctness of NatSpec tags.                                                                                     |              |            |
 | [constructor-syntax](./rules/best-practices/constructor-syntax.md)       | Constructors should use the new constructor keyword.                                                                                       |              |            |
         
 

docs/rules/best-practices/code-complexity.md

@@ -24,7 +24,10 @@ This rule accepts an array of options:
 ```json
 {
   "rules": {
-    "code-complexity": ["warn",7]
+    "code-complexity": [
+      "warn",
+      7
+    ]
   }
 }
 ```

docs/rules/best-practices/explicit-types.md

@@ -27,7 +27,10 @@ This rule accepts an array of options:
 ```json
 {
   "rules": {
-    "explicit-types": ["warn","explicit"]
+    "explicit-types": [
+      "warn",
+      "explicit"
+    ]
   }
 }
 ```

docs/rules/best-practices/function-max-lines.md

@@ -24,7 +24,10 @@ This rule accepts an array of options:
 ```json
 {
   "rules": {
-    "function-max-lines": ["warn",50]
+    "function-max-lines": [
+      "warn",
+      50
+    ]
   }
 }
 ```

docs/rules/best-practices/max-line-length.md

@@ -26,7 +26,10 @@ This rule accepts an array of options:
 ```json
 {
   "rules": {
-    "max-line-length": ["error",120]
+    "max-line-length": [
+      "error",
+      120
+    ]
   }
 }
 ```

docs/rules/best-practices/max-states-count.md

@@ -27,7 +27,10 @@ This rule accepts an array of options:
 ```json
 {
   "rules": {
-    "max-states-count": ["warn",15]
+    "max-states-count": [
+      "warn",
+      15
+    ]
   }
 }
 ```

docs/rules/best-practices/reason-string.md

@@ -27,7 +27,12 @@ This rule accepts an array of options:
 ```json
 {
   "rules": {
-    "reason-string": ["warn",{"maxLength":32}]
+    "reason-string": [
+      "warn",
+      {
+        "maxLength": 32
+      }
+    ]
   }
 }
 ```

docs/rules/best-practices/use-natspec.md

@@ -0,0 +1,138 @@
+---
+warning:     "This is a dynamically generated file. Do not edit manually."
+layout:      "default"
+title:       "use-natspec | Solhint"
+---
+
+# use-natspec
+![Category Badge](https://img.shields.io/badge/-Best%20Practices%20Rules-informational)
+![Default Severity Badge warn](https://img.shields.io/badge/Default%20Severity-warn-yellow)
+
+## Description
+Enforces the presence and correctness of NatSpec tags.
+
+## Options
+This rule accepts an array of options:
+
+| Index | Description                                                              | Default Value        |
+| ----- | ------------------------------------------------------------------------ | -------------------- |
+| 0     | Rule severity. Must be one of "error", "warn", "off".                    | warn                 |
+| 1     | A JSON object with natspec properties. See EXAMPLE CONFIG section below. | Check EXAMPLE CONFIG |
+
+
+### Example Config
+```json
+{
+  "rules": {
+    "use-natspec": [
+      "warn",
+      {
+        "title": {
+          "enabled": true,
+          "ignore": {}
+        },
+        "author": {
+          "enabled": true,
+          "ignore": {}
+        },
+        "notice": {
+          "enabled": true,
+          "ignore": {}
+        },
+        "param": {
+          "enabled": true,
+          "ignore": {}
+        },
+        "return": {
+          "enabled": true,
+          "ignore": {}
+        }
+      }
+    ]
+  }
+}
+```
+
+### Notes
+- If a function or return value has unnamed parameters (e.g. `function foo(uint256)`), the rule only checks the number of `@param` or `@return` tags, not their names.
+- If a function or variable has `@inheritdoc`, the rule skips the validation.
+- The rule supports both `///` and `/** */` style NatSpec comments.
+- If a custom config is provided, it is merged with the default config. Only the overridden fields need to be specified.
+
+## Examples
+### 👍 Examples of **correct** code for this rule
+
+#### Contract with valid NatSpec
+
+```solidity
+
+                /// @title Token contract
+                /// @author Me
+                /// @notice This contract handles tokens
+                contract Token {
+                  /// @notice Transfers tokens
+                  /// @param to The recipient address
+                  /// @param amount The amount to transfer
+                  /// @return success Whether the transfer succeeded
+                  function transfer(address to, uint256 amount) public returns (bool success) {
+                    return true;
+                  }
+                }
+              
+```
+
+#### You can disable specific tags globally or by type/name using the `ignore` option in the config. For example:
+
+```solidity
+{
+                "use-natspec": [
+                  "warn",
+                  {
+                    "title": {
+                      "enabled": true,
+                      "ignore": {
+                        "contract": ["MyContract"],
+                        "*": ["LegacyContract"]
+                      }
+                    },
+                    "param": { "enabled": false }
+                  }
+                ]
+              }
+```
+
+#### The default configuration enables all checks with no ignore rules:
+
+```solidity
+{
+                "title": { "enabled": true, "ignore": {} },
+                "author": { "enabled": true, "ignore": {} },
+                "notice": { "enabled": true, "ignore": {} },
+                "param": { "enabled": true, "ignore": {} },
+                "return": { "enabled": true, "ignore": {} }
+              }
+```
+
+### 👎 Examples of **incorrect** code for this rule
+
+#### Missing @notice and incorrect @param and @return tags
+
+```solidity
+
+                /// @title Token contract
+                contract Token {
+                  /// @param wrongParam Not matching actual parameter
+                  function transfer(address to) public returns (bool) {
+                    return true;
+                  }
+                }
+                
+```
+
+## Version
+This rule was introduced in the latest version.
+
+## Resources
+- [Rule source](https://github.com/protofire/solhint/blob/master/lib/rules/best-practices/use-natspec.js)
+- [Document source](https://github.com/protofire/solhint/blob/master/docs/rules/best-practices/use-natspec.md)
+- [Test cases](https://github.com/protofire/solhint/blob/master/test/rules/best-practices/use-natspec.js)

docs/rules/miscellaneous/import-path-check.md

@@ -27,7 +27,12 @@ This rule accepts an array of options:
 ```json
 {
   "rules": {
-    "import-path-check": ["warn",["[~dependenciesPath]"]]
+    "import-path-check": [
+      "warn",
+      [
+        "[~dependenciesPath]"
+      ]
+    ]
   }
 }
 ```