feat(forge-lint): new LateLintPass + support code snippets

Cargo.toml

@@ -410,3 +410,9 @@ zip-extract = "=0.2.1"
 ## foundry
 # foundry-compilers = { git = "https://github.com/foundry-rs/compilers.git", rev = "e4a9b04" }
 # foundry-fork-db = { git = "https://github.com/foundry-rs/foundry-fork-db", rev = "811a61a" }
+
+# solar
+solar-ast = { git = "https://github.com/0xrusowsky/solar.git", branch = "rusowsky/flatten-with-style" }
+solar-parse = { git = "https://github.com/0xrusowsky/solar.git", branch = "rusowsky/flatten-with-style" }
+solar-interface = { git = "https://github.com/0xrusowsky/solar.git", branch = "rusowsky/flatten-with-style" }
+solar-sema = { git = "https://github.com/0xrusowsky/solar.git", branch = "rusowsky/flatten-with-style" }

crates/lint/src/linter.rs

@@ -3,7 +3,7 @@ use foundry_config::lint::Severity;
 use solar_ast::{visit::Visit, Expr, ItemFunction, ItemStruct, VariableDefinition};
 use solar_interface::{
     data_structures::Never,
-    diagnostics::{DiagBuilder, DiagId, MultiSpan},
+    diagnostics::{DiagBuilder, DiagId, DiagMsg, MultiSpan, Style},
     Session, Span,
 };
 use std::{ops::ControlFlow, path::PathBuf};
@@ -32,6 +32,7 @@ pub trait Lint {
     fn severity(&self) -> Severity;
     fn description(&self) -> &'static str;
     fn help(&self) -> &'static str;
+    fn example(&self) -> Vec<(DiagMsg, Style)>;
 }
 
 pub struct LintContext<'s> {
@@ -44,7 +45,7 @@ impl<'s> LintContext<'s> {
         Self { sess, desc: with_description }
     }
 
-    // Helper method to emit diagnostics easily from passes
+    /// Helper method to emit diagnostics easily from passes
     pub fn emit<L: Lint>(&self, lint: &'static L, span: Span) {
         let desc = if self.desc { lint.description() } else { "" };
         let diag: DiagBuilder<'_, ()> = self
@@ -53,6 +54,7 @@ impl<'s> LintContext<'s> {
             .diag(lint.severity().into(), desc)
             .code(DiagId::new_str(lint.id()))
             .span(MultiSpan::from_span(span))
+            .highlighted_note(lint.example())
             .help(lint.help());
 
         diag.emit();

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

@@ -1,6 +1,5 @@
 use super::AsmKeccak256;
 use crate::{
-    declare_forge_lint,
     linter::EarlyLintPass,
     sol::{Severity, SolLint},
 };
@@ -11,7 +10,12 @@ declare_forge_lint!(
     ASM_KECCAK256,
     Severity::Gas,
     "asm-keccak256",
-    "hash using inline assembly to save gas"
+    "inefficient hashing mechanism",
+    diff: {
+        bad: "bytes32 hash = keccak256(abi.encodePacked(a, b));",
+        good: "bytes32 hash;\nassembly {\n    mstore(0x00, a)\n    mstore(0x20, b)\n    hash := keccak256(0x00, 0x40)\n}",
+        desc: "consider using inline assembly to reduce gas usage, like shown in this example:"
+    }
 );
 
 impl<'ast> EarlyLintPass<'ast> for AsmKeccak256 {

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

@@ -1,7 +1,4 @@
-use crate::{
-    register_lints,
-    sol::{EarlyLintPass, SolLint},
-};
+use crate::sol::{EarlyLintPass, SolLint};
 
 mod keccak;
 use keccak::ASM_KECCAK256;

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

@@ -1,6 +1,5 @@
 use super::IncorrectShift;
 use crate::{
-    declare_forge_lint,
     linter::{EarlyLintPass, LintContext},
     sol::{Severity, SolLint},
 };

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

@@ -1,7 +1,4 @@
-use crate::{
-    register_lints,
-    sol::{EarlyLintPass, SolLint},
-};
+use crate::sol::{EarlyLintPass, SolLint};
 
 mod incorrect_shift;
 use incorrect_shift::INCORRECT_SHIFT;

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

@@ -1,6 +1,5 @@
 use super::{MixedCaseFunction, MixedCaseVariable};
 use crate::{
-    declare_forge_lint,
     linter::{EarlyLintPass, LintContext},
     sol::{Severity, SolLint},
 };

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

@@ -1,7 +1,4 @@
-use crate::{
-    register_lints,
-    sol::{EarlyLintPass, SolLint},
-};
+use crate::sol::{EarlyLintPass, SolLint};
 
 mod mixed_case;
 use mixed_case::{MIXED_CASE_FUNCTION, MIXED_CASE_VARIABLE};

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

@@ -1,6 +1,5 @@
 use super::PascalCaseStruct;
 use crate::{
-    declare_forge_lint,
     linter::{EarlyLintPass, LintContext},
     sol::{Severity, SolLint},
 };

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

@@ -1,6 +1,5 @@
 use super::ScreamingSnakeCase;
 use crate::{
-    declare_forge_lint,
     linter::{EarlyLintPass, LintContext},
     sol::{Severity, SolLint},
 };

crates/lint/src/sol/macros.rs

@@ -1,31 +1,99 @@
+#[macro_export]
+macro_rules! link {
+    ($url:expr) => {
+        concat!("\x1b]8;;", $url, "\x1b\\", $url, "\x1b]8;;\x1b\\")
+    };
+}
+
 /// Macro for defining lints and relevant metadata for the Solidity linter.
 ///
 /// # Parameters
 ///
 /// Each lint requires the following input fields:
-/// - `$id`: Identitifier of the generated `SolLint` constant.
+/// - `$id`: Identifier of the generated `SolLint` constant.
 /// - `$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.
+/// - `$example` (optional): Can be omitted, a generic message string, or a `diff: { bad: "...",
+///   good: "...", desc: "..." }` block with optional description.
 ///
 /// # 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) => {
-        // Declare the static `Lint` metadata
+    // Form with diff examples and an example description
+    (
+        $id:ident,
+        $severity:expr,
+        $str_id:expr,
+        $desc:expr,
+        diff: {
+            bad: $bad:expr,
+            good: $good:expr,
+            desc: $desc_:expr
+        }
+    ) => {
+        pub static $id: SolLint = SolLint {
+            id: $str_id,
+            severity: $severity,
+            description: $desc,
+            help: link!(concat!("https://book.getfoundry.sh/reference/forge/forge-lint#", $str_id)),
+            example: Some($crate::sol::LintExample::Diff {
+                bad: $bad,
+                good: $good,
+                desc: Some($desc_),
+            }),
+        };
+    };
+
+    // Form with diff examples but without an example description
+    (
+        $id:ident,
+        $severity:expr,
+        $str_id:expr,
+        $desc:expr,
+        diff: {
+            bad: $bad:expr,
+            good: $good:expr
+        }
+    ) => {
         pub static $id: SolLint = SolLint {
             id: $str_id,
             severity: $severity,
             description: $desc,
-            help: concat!("https://book.getfoundry.sh/reference/forge/forge-lint#", $str_id),
+            help: link!(concat!("https://book.getfoundry.sh/reference/forge/forge-lint#", $str_id)),
+            example: Some($crate::sol::LintExample::Diff { bad: $bad, good: $good, context: None }),
         };
     };
 
+    // Form with a general purpose example
+    (
+        $id:ident,
+        $severity:expr,
+        $str_id:expr,
+        $desc:expr,
+        $example:expr
+    ) => {
+        pub static $id: SolLint = SolLint {
+            id: $str_id,
+            severity: $severity,
+            description: $desc,
+            help: link!(concat!("https://book.getfoundry.sh/reference/forge/forge-lint#", $str_id)),
+            example: Some($crate::sol::LintExample::General($examples)),
+        };
+    };
+
+    // Basic form without examples
     ($id:ident, $severity:expr, $str_id:expr, $desc:expr) => {
-        $crate::declare_forge_lint!($id, $severity, $str_id, $desc, "");
+        pub static $id: SolLint = SolLint {
+            id: $str_id,
+            severity: $severity,
+            description: $desc,
+            help: link!(concat!("https://book.getfoundry.sh/reference/forge/forge-lint#", $str_id)),
+            example: None,
+        };
     };
 }
 

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

@@ -1,6 +1,5 @@
 use super::DivideBeforeMultiply;
 use crate::{
-    declare_forge_lint,
     linter::{EarlyLintPass, LintContext},
     sol::{Severity, SolLint},
 };

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

@@ -1,7 +1,4 @@
-use crate::{
-    register_lints,
-    sol::{EarlyLintPass, SolLint},
-};
+use crate::sol::{EarlyLintPass, SolLint};
 
 mod div_mul;
 use div_mul::DIVIDE_BEFORE_MULTIPLY;