chore: standardize lint help + validate docs existance (#10639)

Author: 0xrusowsky

crates/forge/tests/cli/lint.rs

@@ -1,3 +1,4 @@
+use forge_lint::{linter::Lint, sol::med::REGISTERED_LINTS};
 use foundry_config::{LintSeverity, LinterConfig};
 
 const CONTRACT: &str = r#"
@@ -53,6 +54,7 @@ warning[divide-before-multiply]: multiplication should occur before division to
 16 |         (1 / 2) * 3;
    |         -----------
    |
+   = help: https://book.getfoundry.sh/reference/forge/forge-lint#divide-before-multiply
 
 
 "#]]);
@@ -75,6 +77,7 @@ note[mixed-case-variable]: mutable variables should use mixedCase
 6 |         uint256 VARIABLE_MIXED_CASE_INFO;
   |                 ------------------------
   |
+  = help: https://book.getfoundry.sh/reference/forge/forge-lint#mixed-case-variable
 
 
 "#]]);
@@ -109,6 +112,7 @@ note[mixed-case-variable]: mutable variables should use mixedCase
 6 |         uint256 VARIABLE_MIXED_CASE_INFO;
   |                 ------------------------
   |
+  = help: https://book.getfoundry.sh/reference/forge/forge-lint#mixed-case-variable
 
 
 "#]]);
@@ -134,6 +138,7 @@ warning[divide-before-multiply]: multiplication should occur before division to
 16 |         (1 / 2) * 3;
    |         -----------
    |
+   = help: https://book.getfoundry.sh/reference/forge/forge-lint#divide-before-multiply
 
 
 "#]]);
@@ -160,8 +165,56 @@ warning[incorrect-shift]: the order of args in a shift operation is incorrect
 13 |         result = 8 >> localValue;
    |                  ---------------
    |
+   = help: https://book.getfoundry.sh/reference/forge/forge-lint#incorrect-shift
 
 
 "#
     ]]);
 });
+
+#[tokio::test]
+async fn ensure_lint_rule_docs() {
+    const FOUNDRY_BOOK_LINT_PAGE_URL: &str =
+        "https://book.getfoundry.sh/reference/forge/forge-lint";
+
+    // Fetch the content of the lint reference
+    let content = match reqwest::get(FOUNDRY_BOOK_LINT_PAGE_URL).await {
+        Ok(resp) => {
+            if !resp.status().is_success() {
+                panic!(
+                    "Failed to fetch Foundry Book lint page ({FOUNDRY_BOOK_LINT_PAGE_URL}). Status: {status}",
+                    status = resp.status()
+                );
+            }
+            match resp.text().await {
+                Ok(text) => text,
+                Err(e) => {
+                    panic!("Failed to read response text: {e}");
+                }
+            }
+        }
+        Err(e) => {
+            panic!("Failed to fetch Foundry Book lint page ({FOUNDRY_BOOK_LINT_PAGE_URL}): {e}",);
+        }
+    };
+
+    // Ensure no missing lints
+    let mut missing_lints = Vec::new();
+    for lint in REGISTERED_LINTS {
+        let selector = format!("#{}", lint.id());
+        if !content.contains(&selector) {
+            missing_lints.push(lint.id());
+        }
+    }
+
+    if !missing_lints.is_empty() {
+        let mut msg = String::from(
+            "Foundry Book lint validation failed. The following lints must be added to the docs:\n",
+        );
+        for lint in missing_lints {
+            msg.push_str(&format!("  - {lint}\n"));
+        }
+        msg.push_str("Please open a PR: https://github.com/foundry-rs/book");
+        panic!("{msg}");
+    }
+}

crates/lint/src/linter.rs

@@ -31,9 +31,7 @@ pub trait Lint {
     fn id(&self) -> &'static str;
     fn severity(&self) -> Severity;
     fn description(&self) -> &'static str;
-    fn help(&self) -> Option<&'static str> {
-        None
-    }
+    fn help(&self) -> &'static str;
 }
 
 pub struct LintContext<'s> {
@@ -48,19 +46,14 @@ impl<'s> LintContext<'s> {
 
     // Helper method to emit diagnostics easily from passes
     pub fn emit<L: Lint>(&self, lint: &'static L, span: Span) {
-        let (desc, help) = match (self.desc, lint.help()) {
-            (true, Some(help)) => (lint.description(), help),
-            (true, None) => (lint.description(), ""),
-            (false, _) => ("", ""),
-        };
-
+        let desc = if self.desc { lint.description() } else { "" };
         let diag: DiagBuilder<'_, ()> = self
             .sess
             .dcx
             .diag(lint.severity().into(), desc)
             .code(DiagId::new_str(lint.id()))
             .span(MultiSpan::from_span(span))
-            .help(help);
+            .help(lint.help());
 
         diag.emit();
     }

crates/lint/src/sol/gas/keccak.rs

@@ -11,8 +11,7 @@ declare_forge_lint!(
     ASM_KECCAK256,
     Severity::Gas,
     "asm-keccak256",
-    "hash using inline assembly to save gas",
-    ""
+    "hash using inline assembly to save gas"
 );
 
 impl<'ast> EarlyLintPass<'ast> for AsmKeccak256 {

crates/lint/src/sol/high/incorrect_shift.rs

@@ -10,8 +10,7 @@ declare_forge_lint!(
     INCORRECT_SHIFT,
     Severity::High,
     "incorrect-shift",
-    "the order of args in a shift operation is incorrect",
-    ""
+    "the order of args in a shift operation is incorrect"
 );
 
 impl<'ast> EarlyLintPass<'ast> for IncorrectShift {

crates/lint/src/sol/info/mixed_case.rs

@@ -10,8 +10,7 @@ declare_forge_lint!(
     MIXED_CASE_FUNCTION,
     Severity::Info,
     "mixed-case-function",
-    "function names should use mixedCase",
-    "https://docs.soliditylang.org/en/latest/style-guide.html#function-names"
+    "function names should use mixedCase"
 );
 
 impl<'ast> EarlyLintPass<'ast> for MixedCaseFunction {

crates/lint/src/sol/info/pascal_case.rs

@@ -10,8 +10,7 @@ declare_forge_lint!(
     PASCAL_CASE_STRUCT,
     Severity::Info,
     "pascal-case-struct",
-    "structs should use PascalCase",
-    "https://docs.soliditylang.org/en/latest/style-guide.html#struct-names"
+    "structs should use PascalCase"
 );
 
 impl<'ast> EarlyLintPass<'ast> for PascalCaseStruct {

crates/lint/src/sol/info/screaming_snake_case.rs

@@ -10,8 +10,7 @@ declare_forge_lint!(
     SCREAMING_SNAKE_CASE_CONSTANT,
     Severity::Info,
     "screaming-snake-case-const",
-    "constants should use SCREAMING_SNAKE_CASE",
-    "https://docs.soliditylang.org/en/latest/style-guide.html#constants"
+    "constants should use SCREAMING_SNAKE_CASE"
 );
 
 declare_forge_lint!(

crates/lint/src/sol/macros.rs

@@ -7,16 +7,20 @@
 /// - `$severity`: The `Severity` of the lint (e.g. `High`, `Med`, `Low`, `Info`, `Gas`).
 /// - `$str_id`: A unique identifier used to reference a specific lint during configuration.
 /// - `$desc`: A short description of the lint.
-/// - `$help` (optional): Link to additional information about the lint or best practices.
+///
+/// # Note
+/// Each lint must have a `help` section in the foundry book. This help field is auto-generated by
+/// the macro. Because of that, to ensure that new lint rules have their corresponding docs in the
+/// book, the existence of the lint rule's help section is validated with a unit test.
 #[macro_export]
 macro_rules! declare_forge_lint {
-    ($id:ident, $severity:expr, $str_id:expr, $desc:expr, $help:expr) => {
+    ($id:ident, $severity:expr, $str_id:expr, $desc:expr) => {
         // Declare the static `Lint` metadata
         pub static $id: SolLint = SolLint {
             id: $str_id,
             severity: $severity,
             description: $desc,
-            help: if $help.is_empty() { None } else { Some($help) },
+            help: concat!("https://book.getfoundry.sh/reference/forge/forge-lint#", $str_id),
         };
     };
 

crates/lint/src/sol/med/div_mul.rs

@@ -10,8 +10,7 @@ declare_forge_lint!(
     DIVIDE_BEFORE_MULTIPLY,
     Severity::Med,
     "divide-before-multiply",
-    "multiplication should occur before division to avoid loss of precision",
-    ""
+    "multiplication should occur before division to avoid loss of precision"
 );
 
 impl<'ast> EarlyLintPass<'ast> for DivideBeforeMultiply {

crates/lint/src/sol/mod.rs

@@ -159,7 +159,7 @@ pub enum SolLintError {
 pub struct SolLint {
     id: &'static str,
     description: &'static str,
-    help: Option<&'static str>,
+    help: &'static str,
     severity: Severity,
 }
 
@@ -173,7 +173,7 @@ impl Lint for SolLint {
     fn description(&self) -> &'static str {
         self.description
     }
-    fn help(&self) -> Option<&'static str> {
+    fn help(&self) -> &'static str {
         self.help
     }
 }