new rule - immutable vars naming

protofire · Jul 27, 2023 · acf4cea · acf4cea
1 parent 7bb8a28
commit acf4cea
Show file tree

Hide file tree

Showing 25 changed files with 329 additions and 42 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -18,6 +18,7 @@ module.exports = {
     'global-require': 'off',
     'no-bitwise': 'off',
     'no-console': 'off',
+    'func-names': 'off',
     'no-continue': 'off',
     'no-else-return': 'off',
     'no-param-reassign': 'off',

diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ convertLib.sol
 antlr4.jar
 /docs/.sass-cache/
 _temp/
+.solhint.json
diff --git a/docs/rules.md b/docs/rules.md
@@ -12,10 +12,10 @@ title:       "Rule Index of Solhint"
 | [function-max-lines](./rules/best-practises/function-max-lines.md) | Function body contains "count" lines but allowed no more than maxlines.                                               |             |
 | [max-line-length](./rules/best-practises/max-line-length.md)       | Line length must be no more than maxlen.                                                                              |             |
 | [max-states-count](./rules/best-practises/max-states-count.md)     | Contract has "some count" states declarations but allowed no more than maxstates.                                     | ✔️          |
-| [no-console](./rules/best-practises/no-console.md)                 | No console.log/logInt/logBytesX/logString/etc & No hardhat and forge-std console.sol import statements                | ✔️          |
+| [no-console](./rules/best-practises/no-console.md)                 | No console.log/logInt/logBytesX/logString/etc & No hardhat and forge-std console.sol import statements.               | ✔️          |
 | [no-empty-blocks](./rules/best-practises/no-empty-blocks.md)       | Code contains empty block.                                                                                            | ✔️          |
-| [no-global-import](./rules/best-practises/no-global-import.md)     | Import statement includes an entire file instead of selected symbols                                                  | ✔️          |
-| [no-unused-import](./rules/best-practises/no-unused-import.md)     | Imported name is not used                                                                                             | ✔️          |
+| [no-global-import](./rules/best-practises/no-global-import.md)     | Import statement includes an entire file instead of selected symbols.                                                 | ✔️          |
+| [no-unused-import](./rules/best-practises/no-unused-import.md)     | Imported name is not used.                                                                                            | ✔️          |
 | [no-unused-vars](./rules/best-practises/no-unused-vars.md)         | Variable "name" is unused.                                                                                            | ✔️          |
 | [payable-fallback](./rules/best-practises/payable-fallback.md)     | When fallback is not payable you will not be able to receive ethers.                                                  | ✔️          |
 | [reason-string](./rules/best-practises/reason-string.md)           | Require or revert statement must have a reason string and check that each reason string is at most N characters long. | ✔️          |
@@ -32,22 +32,23 @@ title:       "Rule Index of Solhint"
 
 ## Style Guide Rules
 
-| Rule Id                                                                              | Error                                                                                  | Recommended |
-| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------- |
-| [const-name-snakecase](./rules/naming/const-name-snakecase.md)                       | Constant name must be in capitalized SNAKE_CASE.                                       | ✔️          |
-| [contract-name-camelcase](./rules/naming/contract-name-camelcase.md)                 | Contract name must be in CamelCase.                                                    | ✔️          |
-| [event-name-camelcase](./rules/naming/event-name-camelcase.md)                       | Event name must be in CamelCase.                                                       | ✔️          |
-| [func-name-mixedcase](./rules/naming/func-name-mixedcase.md)                         | Function name must be in mixedCase.                                                    | ✔️          |
-| [func-param-name-mixedcase](./rules/naming/func-param-name-mixedcase.md)             | Function param name must be in mixedCase                                               |             |
-| [modifier-name-mixedcase](./rules/naming/modifier-name-mixedcase.md)                 | Modifier name must be in mixedCase.                                                    |             |
-| [named-parameters-mapping](./rules/naming/named-parameters-mapping.md)               | Solidity v0.8.18 introduced named parameters on the mappings definition                |             |
-| [private-vars-leading-underscore](./rules/naming/private-vars-leading-underscore.md) | Private and internal names must start with a single underscore.                        |             |
-| [use-forbidden-name](./rules/naming/use-forbidden-name.md)                           | Avoid to use letters 'I', 'l', 'O' as identifiers.                                     | ✔️          |
-| [var-name-mixedcase](./rules/naming/var-name-mixedcase.md)                           | Variable name must be in mixedCase.                                                    | ✔️          |
-| [func-order](./rules/order/func-order.md)                                            | Function order is incorrect.                                                           |             |
-| [imports-on-top](./rules/order/imports-on-top.md)                                    | Import statements must be on top.                                                      | ✔️          |
-| [ordering](./rules/order/ordering.md)                                                | Check order of elements in file and inside each contract, according to the style guide |             |
-| [visibility-modifier-order](./rules/order/visibility-modifier-order.md)              | Visibility modifier must be first in list of modifiers.                                | ✔️          |
+| Rule Id                                                                              | Error                                                                                                   | Recommended |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------- |
+| [const-name-snakecase](./rules/naming/const-name-snakecase.md)                       | Constant name must be in capitalized SNAKE_CASE. (Does not check IMMUTABLES, use immutable-vars-naming) | ✔️          |
+| [contract-name-camelcase](./rules/naming/contract-name-camelcase.md)                 | Contract name must be in CamelCase.                                                                     | ✔️          |
+| [event-name-camelcase](./rules/naming/event-name-camelcase.md)                       | Event name must be in CamelCase.                                                                        | ✔️          |
+| [func-name-mixedcase](./rules/naming/func-name-mixedcase.md)                         | Function name must be in mixedCase.                                                                     | ✔️          |
+| [func-param-name-mixedcase](./rules/naming/func-param-name-mixedcase.md)             | Function param name must be in mixedCase.                                                               |             |
+| [immutable-vars-naming](./rules/naming/immutable-vars-naming.md)                     | Check Immutable variables. Capitalized SNAKE_CASE or mixedCase depending on configuration.              | ✔️          |
+| [modifier-name-mixedcase](./rules/naming/modifier-name-mixedcase.md)                 | Modifier name must be in mixedCase.                                                                     |             |
+| [named-parameters-mapping](./rules/naming/named-parameters-mapping.md)               | Solidity v0.8.18 introduced named parameters on the mappings definition.                                |             |
+| [private-vars-leading-underscore](./rules/naming/private-vars-leading-underscore.md) | Private and internal names must start with a single underscore.                                         |             |
+| [use-forbidden-name](./rules/naming/use-forbidden-name.md)                           | Avoid to use letters 'I', 'l', 'O' as identifiers.                                                      | ✔️          |
+| [var-name-mixedcase](./rules/naming/var-name-mixedcase.md)                           | Variable name must be in mixedCase. (Does not check IMMUTABLES, use immutable-vars-naming)              | ✔️          |
+| [func-order](./rules/order/func-order.md)                                            | Function order is incorrect.                                                                            |             |
+| [imports-on-top](./rules/order/imports-on-top.md)                                    | Import statements must be on top.                                                                       | ✔️          |
+| [ordering](./rules/order/ordering.md)                                                | Check order of elements in file and inside each contract, according to the style guide.                 |             |
+| [visibility-modifier-order](./rules/order/visibility-modifier-order.md)              | Visibility modifier must be first in list of modifiers.                                                 | ✔️          |
         
 
 ## Security Rules

diff --git a/docs/rules/best-practises/no-console.md b/docs/rules/best-practises/no-console.md
@@ -14,7 +14,7 @@ title:       "no-console | Solhint"
 
 
 ## Description
-No console.log/logInt/logBytesX/logString/etc & No hardhat and forge-std console.sol import statements
+No console.log/logInt/logBytesX/logString/etc & No hardhat and forge-std console.sol import statements.
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to error.

diff --git a/docs/rules/best-practises/no-global-import.md b/docs/rules/best-practises/no-global-import.md
@@ -12,7 +12,7 @@ title:       "no-global-import | Solhint"
 
 
 ## Description
-Import statement includes an entire file instead of selected symbols
+Import statement includes an entire file instead of selected symbols.
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to warn.

diff --git a/docs/rules/best-practises/no-unused-import.md b/docs/rules/best-practises/no-unused-import.md
@@ -12,7 +12,7 @@ title:       "no-unused-import | Solhint"
 
 
 ## Description
-Imported name is not used
+Imported name is not used.
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to warn.

diff --git a/docs/rules/naming/const-name-snakecase.md b/docs/rules/naming/const-name-snakecase.md
@@ -12,7 +12,7 @@ title:       "const-name-snakecase | Solhint"
 
 
 ## Description
-Constant name must be in capitalized SNAKE_CASE.
+Constant name must be in capitalized SNAKE_CASE. (Does not check IMMUTABLES, use immutable-vars-naming)
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to warn.

diff --git a/docs/rules/naming/func-param-name-mixedcase.md b/docs/rules/naming/func-param-name-mixedcase.md
@@ -9,7 +9,7 @@ title:       "func-param-name-mixedcase | Solhint"
 ![Default Severity Badge warn](https://img.shields.io/badge/Default%20Severity-warn-yellow)
 
 ## Description
-Function param name must be in mixedCase
+Function param name must be in mixedCase.
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to warn.

diff --git a/docs/rules/naming/immutable-vars-naming.md b/docs/rules/naming/immutable-vars-naming.md
@@ -0,0 +1,45 @@
+---
+warning:     "This is a dynamically generated file. Do not edit manually."
+layout:      "default"
+title:       "immutable-vars-naming | Solhint"
+---
+
+# immutable-vars-naming
+![Recommended Badge](https://img.shields.io/badge/-Recommended-brightgreen)
+![Category Badge](https://img.shields.io/badge/-Style%20Guide%20Rules-informational)
+![Default Severity Badge warn](https://img.shields.io/badge/Default%20Severity-warn-yellow)
+> The {"extends": "solhint:recommended"} property in a configuration file enables this rule.
+
+
+## Description
+Check Immutable variables. Capitalized SNAKE_CASE or mixedCase depending on configuration.
+
+## 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 a single property "immutablesAsConstants" as boolean specifying if immutable variables should be treated as constants | {"immutablesAsConstants":true} |
+
+
+### Example Config
+```json
+{
+  "rules": {
+    "immutable-vars-naming": ["warn",{"immutablesAsConstants":true}]
+  }
+}
+```
+
+
+## Examples
+This rule does not have examples.
+
+## Version
+This rule is introduced in the latest version.
+
+## Resources
+- [Rule source](https://github.com/protofire/solhint/tree/master/lib/rules/naming/immutable-vars-naming.js)
+- [Document source](https://github.com/protofire/solhint/tree/master/docs/rules/naming/immutable-vars-naming.md)
+- [Test cases](https://github.com/protofire/solhint/tree/master/test/rules/naming/immutable-vars-naming.js)
diff --git a/docs/rules/naming/named-parameters-mapping.md b/docs/rules/naming/named-parameters-mapping.md
@@ -9,7 +9,7 @@ title:       "named-parameters-mapping | Solhint"
 ![Default Severity Badge off](https://img.shields.io/badge/Default%20Severity-off-undefined)
 
 ## Description
-Solidity v0.8.18 introduced named parameters on the mappings definition
+Solidity v0.8.18 introduced named parameters on the mappings definition.
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to off.

diff --git a/docs/rules/naming/var-name-mixedcase.md b/docs/rules/naming/var-name-mixedcase.md
@@ -12,7 +12,7 @@ title:       "var-name-mixedcase | Solhint"
 
 
 ## Description
-Variable name must be in mixedCase.
+Variable name must be in mixedCase. (Does not check IMMUTABLES, use immutable-vars-naming)
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to warn.

diff --git a/docs/rules/order/ordering.md b/docs/rules/order/ordering.md
@@ -9,7 +9,7 @@ title:       "ordering | Solhint"
 ![Default Severity Badge warn](https://img.shields.io/badge/Default%20Severity-warn-yellow)
 
 ## Description
-Check order of elements in file and inside each contract, according to the style guide
+Check order of elements in file and inside each contract, according to the style guide.
 
 ## Options
 This rule accepts a string option of rule severity. Must be one of "error", "warn", "off". Default to warn.

diff --git a/lib/rules/best-practises/no-console.js b/lib/rules/best-practises/no-console.js
@@ -5,7 +5,7 @@ const meta = {
   type: 'best-practises',
   docs: {
     description:
-      'No console.log/logInt/logBytesX/logString/etc & No hardhat and forge-std console.sol import statements',
+      'No console.log/logInt/logBytesX/logString/etc & No hardhat and forge-std console.sol import statements.',
     category: 'Best Practise Rules',
     examples: {
       bad: [

diff --git a/lib/rules/best-practises/no-global-import.js b/lib/rules/best-practises/no-global-import.js
@@ -5,7 +5,7 @@ const meta = {
   type: 'best-practises',
 
   docs: {
-    description: 'Import statement includes an entire file instead of selected symbols',
+    description: 'Import statement includes an entire file instead of selected symbols.',
     category: 'Best Practise Rules',
     examples: {
       bad: [

diff --git a/lib/rules/best-practises/no-unused-import.js b/lib/rules/best-practises/no-unused-import.js
@@ -6,7 +6,7 @@ const meta = {
   type: 'best-practises',
 
   docs: {
-    description: 'Imported name is not used',
+    description: 'Imported name is not used.',
     category: 'Best Practise Rules',
   },
 

diff --git a/lib/rules/naming/const-name-snakecase.js b/lib/rules/naming/const-name-snakecase.js
@@ -6,7 +6,7 @@ const meta = {
   type: 'naming',
 
   docs: {
-    description: 'Constant name must be in capitalized SNAKE_CASE.',
+    description: 'Constant name must be in capitalized SNAKE_CASE. (Does not check IMMUTABLES, use immutable-vars-naming)',
     category: 'Style Guide Rules',
   },
 

diff --git a/lib/rules/naming/func-param-name-mixedcase.js b/lib/rules/naming/func-param-name-mixedcase.js
@@ -6,7 +6,7 @@ const meta = {
   type: 'naming',
 
   docs: {
-    description: 'Function param name must be in mixedCase',
+    description: 'Function param name must be in mixedCase.',
     category: 'Style Guide Rules',
   },
 

diff --git a/lib/rules/naming/immutable-vars-naming.js b/lib/rules/naming/immutable-vars-naming.js
@@ -0,0 +1,80 @@
+const BaseChecker = require('../base-checker')
+const naming = require('../../common/identifier-naming')
+const { severityDescription } = require('../../doc/utils')
+
+const DEFAULT_INMUTABLE_AS_CONSTANTS = true
+const DEFAULT_SEVERITY = 'warn'
+const DEFAULT_OPTION = { immutablesAsConstants: DEFAULT_INMUTABLE_AS_CONSTANTS }
+
+const ruleId = 'immutable-vars-naming'
+const meta = {
+  type: 'naming',
+
+  docs: {
+    description:
+      'Check Immutable variables. Capitalized SNAKE_CASE or mixedCase depending on configuration.',
+    category: 'Style Guide Rules',
+    options: [
+      {
+        description: severityDescription,
+        default: DEFAULT_SEVERITY,
+      },
+      {
+        description:
+          'A JSON object with a single property "immutablesAsConstants" as boolean specifying if immutable variables should be treated as constants',
+        default: JSON.stringify(DEFAULT_OPTION),
+      },
+    ],
+  },
+
+  isDefault: false,
+  recommended: true,
+  defaultSetup: [DEFAULT_SEVERITY, DEFAULT_OPTION],
+
+  schema: {
+    type: 'object',
+    properties: {
+      immutablesAsConstants: {
+        type: 'boolean',
+      },
+    },
+  },
+}
+
+class ImmutableVarsNamingChecker extends BaseChecker {
+  constructor(reporter, config) {
+    super(reporter, ruleId, meta)
+
+    this.treatImmutablesAsConstants =
+      config &&
+      config.getObjectPropertyBoolean(
+        ruleId,
+        'immutablesAsConstants',
+        DEFAULT_INMUTABLE_AS_CONSTANTS
+      )
+  }
+
+  VariableDeclaration(node) {
+    if (node.isImmutable) {
+      if (this.treatImmutablesAsConstants) {
+        this.validateImmutableAsConstantName(node)
+      } else {
+        this.validateImmutableAsRegularVariables(node)
+      }
+    }
+  }
+
+  validateImmutableAsConstantName(node) {
+    if (naming.isNotUpperSnakeCase(node.name)) {
+      this.error(node, 'Immutable variables name are set to be in capitalized SNAKE_CASE')
+    }
+  }
+
+  validateImmutableAsRegularVariables(node) {
+    if (naming.isNotMixedCase(node.name)) {
+      this.error(node, 'Immutable variables names are set to be in mixedCase')
+    }
+  }
+}
+
+module.exports = ImmutableVarsNamingChecker
diff --git a/lib/rules/naming/index.js b/lib/rules/naming/index.js
@@ -4,10 +4,11 @@ const EventNameCamelcaseChecker = require('./event-name-camelcase')
 const FuncNameMixedcaseChecker = require('./func-name-mixedcase')
 const FuncParamNameMixedcaseChecker = require('./func-param-name-mixedcase')
 const ModifierNameMixedcaseChecker = require('./modifier-name-mixedcase')
-const PrivateVarsLeadingUnderscore = require('./private-vars-leading-underscore')
+const PrivateVarsLeadingUnderscoreChecker = require('./private-vars-leading-underscore')
 const UseForbiddenNameChecker = require('./use-forbidden-name')
 const VarNameMixedcaseChecker = require('./var-name-mixedcase')
-const NamedParametersMapping = require('./named-parameters-mapping')
+const NamedParametersMappingChecker = require('./named-parameters-mapping')
+const ImmutableVarsNamingChecker = require('./immutable-vars-naming')
 
 module.exports = function checkers(reporter, config) {
   return [
@@ -17,9 +18,10 @@ module.exports = function checkers(reporter, config) {
     new FuncNameMixedcaseChecker(reporter),
     new FuncParamNameMixedcaseChecker(reporter),
     new ModifierNameMixedcaseChecker(reporter),
-    new PrivateVarsLeadingUnderscore(reporter, config),
+    new PrivateVarsLeadingUnderscoreChecker(reporter, config),
     new UseForbiddenNameChecker(reporter),
     new VarNameMixedcaseChecker(reporter),
-    new NamedParametersMapping(reporter),
+    new NamedParametersMappingChecker(reporter),
+    new ImmutableVarsNamingChecker(reporter, config),
   ]
 }