feat: allow enforcing natspec on specific items (#42)

* fix(variable): raise error on missing natspec

* feat: add config to enforce some items have natspec

* feat(error): allow to enforce natspec

* feat(event): allow to enforce natspec

* feat(function): allow to enforce natspec

* feat(modifier): allow to enforce natspec

* feat(struct): allow to enforce natspec

* feat(constructor): allow to enforce natspec

* feat(enum): allow to enforce natspec

* chore: update readme

* docs: update readme

* docs: add comment

Author: beeb

.env.example

@@ -1,9 +1,10 @@
 LINTSPEC_PATHS=[path/to/file.sol,path/to/dir] # paths to files and folders to analyze
-LINTSPEC_EXCLUDE=[path/to/ignore] # paths to files or folders to exclude, see also `.nsignore`
-LINTSPEC_INHERITDOC=true     # enforce that all overridden, public and external items have `@inheritdoc`
-LINTSPEC_CONSTRUCTOR=false   # enforce that constructors have natspec
-LINTSPEC_STRUCT_PARAMS=false # enforce that structs have `@param` for each member
-LINTSPEC_ENUM_PARAMS=false   # enforce that enums have `@param` for each variant
-LINTSPEC_JSON=false          # output diagnostics as JSON
-LINTSPEC_COMPACT=false       # compact output (minified JSON or compact text)
-LINTSPEC_SORT=false          # sort results by file path
+LINTSPEC_EXCLUDE=[path/to/ignore]    # paths to files or folders to exclude, see also `.nsignore`
+LINTSPEC_INHERITDOC=true             # enforce that all overridden, public and external items have `@inheritdoc`
+LINTSPEC_CONSTRUCTOR=false           # enforce that constructors have natspec
+LINTSPEC_STRUCT_PARAMS=false         # enforce that structs have `@param` for each member
+LINTSPEC_ENUM_PARAMS=false           # enforce that enums have `@param` for each variant
+LINTSPEC_ENFORCE=[variable,struct]   # enforce NatSpec on items even if they don't have params/returns/members
+LINTSPEC_JSON=false                  # output diagnostics as JSON
+LINTSPEC_COMPACT=false               # compact output (minified JSON or compact text)
+LINTSPEC_SORT=false                  # sort results by file path

.lintspec.toml

@@ -5,6 +5,8 @@ inheritdoc = true     # enforce that all overridden, public and external items h
 constructor = false   # enforce that constructors have natspec
 struct_params = false # enforce that structs have `@param` for each member
 enum_params = false   # enforce that enums have `@param` for each variant
-json = false          # output diagnostics as JSON
-compact = false       # compact output (minified JSON or compact text)
-sort = false          # sort results by file path
+# enforce NatSpec on items even if they don't have params/returns/members. Possible values: constructor, enum, error, event, function, modifier, struct, variable
+enforce = ["variable", "struct"]
+json = false                     # output diagnostics as JSON
+compact = false                  # compact output (minified JSON or compact text)
+sort = false                     # sort results by file path

README.md

@@ -68,17 +68,18 @@ 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
-      --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
+  -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 (@dev, @notice) on items even if they don't have params/returns/members (can be used more than once)
+      --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

src/config.rs

@@ -9,6 +9,8 @@ use figment::{
 use serde::{Deserialize, Serialize};
 use serde_with::skip_serializing_none;
 
+use crate::lint::ItemType;
+
 #[derive(Parser, Debug, Clone, Serialize, Deserialize)]
 #[skip_serializing_none]
 #[command(version, about, long_about = None)]
@@ -54,6 +56,11 @@ pub struct Args {
     #[arg(long, num_args = 0..=1, default_missing_value = "true")]
     pub enum_params: Option<bool>,
 
+    /// Enforce NatSpec (@dev, @notice) on items even if they don't have params/returns/members
+    /// (can be used more than once)
+    #[arg(short = 'f', long, name = "TYPE")]
+    pub enforce: Vec<ItemType>,
+
     /// Output diagnostics in JSON format
     ///
     /// Can be set with `--json` (means true), `--json true` or `--json false`.
@@ -86,6 +93,7 @@ pub struct Config {
     pub constructor: bool,
     pub struct_params: bool,
     pub enum_params: bool,
+    pub enforce: Vec<ItemType>,
     pub json: bool,
     pub compact: bool,
     pub sort: bool,
@@ -101,6 +109,7 @@ impl From<Args> for Config {
             constructor: value.constructor.unwrap_or_default(),
             struct_params: value.struct_params.unwrap_or_default(),
             enum_params: value.enum_params.unwrap_or_default(),
+            enforce: value.enforce,
             json: value.json.unwrap_or_default(),
             compact: value.compact.unwrap_or_default(),
             sort: value.sort.unwrap_or_default(),
@@ -119,6 +128,7 @@ pub fn read_config() -> Result<Config> {
             constructor: None,
             struct_params: None,
             enum_params: None,
+            enforce: args.enforce,
             json: None,
             compact: None,
             sort: None,

src/definitions/constructor.rs

@@ -71,17 +71,21 @@ impl Validate for ConstructorDefinition {
             span: self.span(),
             diags: vec![],
         };
-        if !options.constructor || self.params.is_empty() {
-            return out;
-        }
-
         let Some(natspec) = &self.natspec else {
+            if (!options.constructor || self.params.is_empty())
+                && !options.enforce.contains(&ItemType::Constructor)
+            {
+                return out;
+            }
             out.diags.push(Diagnostic {
                 span: self.span(),
                 message: "missing NatSpec".to_string(),
             });
             return out;
         };
+        if !options.constructor || self.params.is_empty() {
+            return out;
+        }
         // check params
         out.diags.append(&mut check_params(natspec, &self.params));
         out
@@ -101,6 +105,7 @@ mod tests {
         constructor: true,
         struct_params: false,
         enum_params: false,
+        enforce: vec![],
     };
 
     fn parse_file(contents: &str) -> ConstructorDefinition {
@@ -203,15 +208,34 @@ mod tests {
             /// @inheritdoc ITest
             constructor(uint256 param1) { } 
         }";
+        let res =
+            parse_file(contents).validate(&ValidationOptions::builder().constructor(true).build());
+        assert_eq!(res.diags.len(), 1);
+        assert_eq!(res.diags[0].message, "@param param1 is missing");
+    }
+
+    #[test]
+    fn test_constructor_enforce() {
+        let contents = "contract Test {
+            constructor() { } 
+        }";
         let res = parse_file(contents).validate(
             &ValidationOptions::builder()
-                .inheritdoc(true) // has no effect on constructor
-                .constructor(true)
-                .struct_params(false)
-                .enum_params(false)
+                .enforce(vec![ItemType::Constructor])
                 .build(),
         );
         assert_eq!(res.diags.len(), 1);
-        assert_eq!(res.diags[0].message, "@param param1 is missing");
+        assert_eq!(res.diags[0].message, "missing NatSpec");
+
+        let contents = "contract Test {
+            /// @notice Some notice
+            constructor() { } 
+        }";
+        let res = parse_file(contents).validate(
+            &ValidationOptions::builder()
+                .enforce(vec![ItemType::Constructor])
+                .build(),
+        );
+        assert!(res.diags.is_empty(), "{:#?}", res.diags);
     }
 }

src/definitions/enumeration.rs

@@ -75,17 +75,20 @@ impl Validate for EnumDefinition {
             span: self.span(),
             diags: vec![],
         };
-        if !options.enum_params {
-            return out;
-        }
         // raise error if no NatSpec is available
         let Some(natspec) = &self.natspec else {
+            if !options.enum_params && !options.enforce.contains(&ItemType::Enum) {
+                return out;
+            }
             out.diags.push(Diagnostic {
                 span: self.span(),
                 message: "missing NatSpec".to_string(),
             });
             return out;
         };
+        if !options.enum_params {
+            return out;
+        }
         out.diags = check_params(natspec, &self.members);
         out
     }
@@ -116,6 +119,7 @@ mod tests {
         constructor: false,
         struct_params: false,
         enum_params: true,
+        enforce: vec![],
     };
 
     fn parse_file(contents: &str) -> EnumDefinition {
@@ -136,14 +140,8 @@ mod tests {
                 Second
             }
         }";
-        let res = parse_file(contents).validate(
-            &ValidationOptions::builder()
-                .inheritdoc(false)
-                .constructor(false)
-                .enum_params(false)
-                .struct_params(false)
-                .build(),
-        );
+        let res =
+            parse_file(contents).validate(&ValidationOptions::builder().inheritdoc(false).build());
         assert!(res.diags.is_empty(), "{:#?}", res.diags);
     }
 
@@ -245,16 +243,39 @@ mod tests {
                 First
             }
         }";
+        let res =
+            parse_file(contents).validate(&ValidationOptions::builder().enum_params(true).build());
+        assert_eq!(res.diags.len(), 1);
+        assert_eq!(res.diags[0].message, "@param First is missing");
+    }
+
+    #[test]
+    fn test_enum_enforce() {
+        let contents = "contract Test {
+            enum Foobar {
+                First
+            }
+        }";
         let res = parse_file(contents).validate(
             &ValidationOptions::builder()
-                .inheritdoc(true) // has no effect for enums
-                .constructor(false)
-                .enum_params(true)
-                .struct_params(false)
+                .enforce(vec![ItemType::Enum])
                 .build(),
         );
         assert_eq!(res.diags.len(), 1);
-        assert_eq!(res.diags[0].message, "@param First is missing");
+        assert_eq!(res.diags[0].message, "missing NatSpec");
+
+        let contents = "contract Test {
+            /// @notice Some notice
+            enum Foobar {
+                First
+            }
+        }";
+        let res = parse_file(contents).validate(
+            &ValidationOptions::builder()
+                .enforce(vec![ItemType::Enum])
+                .build(),
+        );
+        assert!(res.diags.is_empty(), "{:#?}", res.diags);
     }
 
     #[test]

src/definitions/error.rs

@@ -67,19 +67,19 @@ impl Validate for ErrorDefinition {
         .into())
     }
 
-    fn validate(&self, _: &ValidationOptions) -> ItemDiagnostics {
+    fn validate(&self, options: &ValidationOptions) -> ItemDiagnostics {
         let mut out = ItemDiagnostics {
             parent: self.parent(),
             item_type: ItemType::Error,
             name: self.name(),
             span: self.span(),
             diags: vec![],
         };
-        if self.params.is_empty() {
-            return out;
-        }
         // raise error if no NatSpec is available
         let Some(natspec) = &self.natspec else {
+            if self.params.is_empty() && !options.enforce.contains(&ItemType::Error) {
+                return out;
+            }
             out.diags.push(Diagnostic {
                 span: self.span(),
                 message: "missing NatSpec".to_string(),
@@ -104,6 +104,7 @@ mod tests {
         constructor: false,
         struct_params: false,
         enum_params: false,
+        enforce: vec![],
     };
 
     fn parse_file(contents: &str) -> ErrorDefinition {
@@ -200,16 +201,36 @@ mod tests {
             /// @inheritdoc ITest
             error Foobar(uint256 a);
         }";
+        let res = parse_file(contents).validate(&ValidationOptions::default());
+        assert_eq!(res.diags.len(), 1);
+        assert_eq!(res.diags[0].message, "@param a is missing");
+    }
+
+    #[test]
+    fn test_error_enforce() {
+        let contents = "contract Test {
+            error Foobar();
+        }";
         let res = parse_file(contents).validate(
             &ValidationOptions::builder()
-                .inheritdoc(true) // has no effect on error
-                .constructor(false)
-                .struct_params(false)
-                .enum_params(false)
+                .inheritdoc(false)
+                .enforce(vec![ItemType::Error])
                 .build(),
         );
         assert_eq!(res.diags.len(), 1);
-        assert_eq!(res.diags[0].message, "@param a is missing");
+        assert_eq!(res.diags[0].message, "missing NatSpec");
+
+        let contents = "contract Test {
+            /// @notice Some notice
+            error Foobar();
+        }";
+        let res = parse_file(contents).validate(
+            &ValidationOptions::builder()
+                .inheritdoc(false)
+                .enforce(vec![ItemType::Error])
+                .build(),
+        );
+        assert!(res.diags.is_empty(), "{:#?}", res.diags);
     }
 
     #[test]