feat(fmt): rewrite formatter using Solar and a structured algorithm

.gitignore

@@ -1,5 +1,6 @@
 .DS_STORE
 /target*
+/*.sol
 out/
 snapshots/
 out.json
@@ -11,4 +12,4 @@ CLAUDE.md
 node_modules
 dist
 bin
-_
+_

Cargo.toml

@@ -20,6 +20,7 @@ members = [
     "crates/evm/fuzz/",
     "crates/evm/traces/",
     "crates/fmt/",
+    "crates/fmt-2/",
     "crates/forge/",
     "crates/script-sequence/",
     "crates/macros/",
@@ -295,10 +296,7 @@ bytes = "1.10"
 walkdir = "2"
 prettyplease = "0.2"
 base64 = "0.22"
-chrono = { version = "0.4", default-features = false, features = [
-    "clock",
-    "std",
-] }
+chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
 axum = "0.8"
 ciborium = "0.2"
 color-eyre = "0.6"
@@ -354,6 +352,9 @@ flate2 = "1.1"
 
 ## Pinned dependencies. Enabled for the workspace in crates/test-utils.
 
+# testing
+snapbox = { version = "0.6", features = ["json", "regex", "term-svg"] }
+
 # Use unicode-rs which has a smaller binary size than the default ICU4X as the IDNA backend, used
 # by the `url` crate.
 # See the `idna_adapter` README.md for more details: https://docs.rs/crate/idna_adapter/latest

Makefile

@@ -150,4 +150,4 @@ dprint-check: ## Check formatting with dprint
 		echo "Installing dprint..."; \
 		cargo install dprint; \
 	fi
-	dprint check
+	dprint check

crates/common/Cargo.toml

@@ -44,6 +44,7 @@ alloy-transport.workspace = true
 alloy-consensus = { workspace = true, features = ["k256"] }
 alloy-network.workspace = true
 
+solar-interface.workspace = true
 solar-parse.workspace = true
 solar-sema.workspace = true
 

crates/common/src/comments/comment.rs

@@ -2,7 +2,7 @@
 
 use solar_parse::{
     ast::{CommentKind, Span},
-    interface::BytePos,
+    interface::{BytePos, Symbol},
 };
 
 #[derive(Clone, Copy, PartialEq, Debug)]
@@ -17,6 +17,21 @@ pub enum CommentStyle {
     BlankLine,
 }
 
+impl CommentStyle {
+    pub fn is_mixed(&self) -> bool {
+        matches!(self, Self::Mixed)
+    }
+    pub fn is_trailing(&self) -> bool {
+        matches!(self, Self::Trailing)
+    }
+    pub fn is_isolated(&self) -> bool {
+        matches!(self, Self::Isolated)
+    }
+    pub fn is_blank(&self) -> bool {
+        matches!(self, Self::BlankLine)
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct Comment {
     pub lines: Vec<String>,
@@ -53,3 +68,178 @@ impl Comment {
         }
     }
 }
+
+/// A fast conservative estimate on whether the string can contain documentation links.
+/// A pair of square brackets `[]` must exist in the string, but we only search for the
+/// opening bracket because brackets always go in pairs in practice.
+#[inline]
+pub fn may_have_doc_links(s: &str) -> bool {
+    s.contains('[')
+}
+
+/// Makes a doc string more presentable to users.
+/// Used by rustdoc and perhaps other tools, but not by rustc.
+pub fn beautify_doc_string(data: Symbol, kind: CommentKind) -> Symbol {
+    fn get_vertical_trim(lines: &[&str]) -> Option<(usize, usize)> {
+        let mut i = 0;
+        let mut j = lines.len();
+        // first line of all-stars should be omitted
+        if lines.first().is_some_and(|line| line.chars().all(|c| c == '*')) {
+            i += 1;
+        }
+
+        // like the first, a last line of all stars should be omitted
+        if j > i && !lines[j - 1].is_empty() && lines[j - 1].chars().all(|c| c == '*') {
+            j -= 1;
+        }
+
+        if i != 0 || j != lines.len() { Some((i, j)) } else { None }
+    }
+
+    fn get_horizontal_trim(lines: &[&str], kind: CommentKind) -> Option<String> {
+        let mut i = usize::MAX;
+        let mut first = true;
+
+        // In case we have doc comments like `/**` or `/*!`, we want to remove stars if they are
+        // present. However, we first need to strip the empty lines so they don't get in the middle
+        // when we try to compute the "horizontal trim".
+        let lines = match kind {
+            CommentKind::Block => {
+                // Whatever happens, we skip the first line.
+                let mut i = lines
+                    .first()
+                    .map(|l| if l.trim_start().starts_with('*') { 0 } else { 1 })
+                    .unwrap_or(0);
+                let mut j = lines.len();
+
+                while i < j && lines[i].trim().is_empty() {
+                    i += 1;
+                }
+                while j > i && lines[j - 1].trim().is_empty() {
+                    j -= 1;
+                }
+                &lines[i..j]
+            }
+            CommentKind::Line => lines,
+        };
+
+        for line in lines {
+            for (j, c) in line.chars().enumerate() {
+                if j > i || !"* \t".contains(c) {
+                    return None;
+                }
+                if c == '*' {
+                    if first {
+                        i = j;
+                        first = false;
+                    } else if i != j {
+                        return None;
+                    }
+                    break;
+                }
+            }
+            if i >= line.len() {
+                return None;
+            }
+        }
+        Some(lines.first()?[..i].to_string())
+    }
+
+    let data_s = data.as_str();
+    if data_s.contains('\n') {
+        let mut lines = data_s.lines().collect::<Vec<&str>>();
+        let mut changes = false;
+        let lines = if let Some((i, j)) = get_vertical_trim(&lines) {
+            changes = true;
+            // remove whitespace-only lines from the start/end of lines
+            &mut lines[i..j]
+        } else {
+            &mut lines
+        };
+        if let Some(horizontal) = get_horizontal_trim(lines, kind) {
+            changes = true;
+            // remove a "[ \t]*\*" block from each line, if possible
+            for line in lines.iter_mut() {
+                if let Some(tmp) = line.strip_prefix(&horizontal) {
+                    *line = tmp;
+                    if kind == CommentKind::Block
+                        && (*line == "*" || line.starts_with("* ") || line.starts_with("**"))
+                    {
+                        *line = &line[1..];
+                    }
+                }
+            }
+        }
+        if changes {
+            return Symbol::intern(&lines.join("\n"));
+        }
+    }
+    data
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use solar_parse::interface::enter;
+
+    #[test]
+    fn test_block_doc_comment_1() {
+        enter(|| {
+            let comment = "\n * Test \n **  Test\n *   Test\n";
+            let stripped = beautify_doc_string(Symbol::intern(comment), CommentKind::Block);
+            assert_eq!(stripped.as_str(), " Test \n*  Test\n   Test");
+        })
+    }
+
+    #[test]
+    fn test_block_doc_comment_2() {
+        enter(|| {
+            let comment = "\n * Test\n *  Test\n";
+            let stripped = beautify_doc_string(Symbol::intern(comment), CommentKind::Block);
+            assert_eq!(stripped.as_str(), " Test\n  Test");
+        })
+    }
+
+    #[test]
+    fn test_block_doc_comment_3() {
+        enter(|| {
+            let comment = "\n let a: *i32;\n *a = 5;\n";
+            let stripped = beautify_doc_string(Symbol::intern(comment), CommentKind::Block);
+            assert_eq!(stripped.as_str(), "let a: *i32;\n*a = 5;");
+        })
+    }
+
+    #[test]
+    fn test_line_doc_comment() {
+        enter(|| {
+            let stripped = beautify_doc_string(Symbol::intern(" test"), CommentKind::Line);
+            assert_eq!(stripped.as_str(), " test");
+            let stripped = beautify_doc_string(Symbol::intern("! test"), CommentKind::Line);
+            assert_eq!(stripped.as_str(), "! test");
+            let stripped = beautify_doc_string(Symbol::intern("test"), CommentKind::Line);
+            assert_eq!(stripped.as_str(), "test");
+            let stripped = beautify_doc_string(Symbol::intern("!test"), CommentKind::Line);
+            assert_eq!(stripped.as_str(), "!test");
+        })
+    }
+
+    #[test]
+    fn test_doc_blocks() {
+        enter(|| {
+            let stripped = beautify_doc_string(
+                Symbol::intern(" # Returns\n     *\n     "),
+                CommentKind::Block,
+            );
+            assert_eq!(stripped.as_str(), " # Returns\n\n");
+
+            let stripped = beautify_doc_string(
+                Symbol::intern("\n     * # Returns\n     *\n     "),
+                CommentKind::Block,
+            );
+            assert_eq!(stripped.as_str(), " # Returns\n\n");
+
+            let stripped = beautify_doc_string(Symbol::intern("\n *     a\n "), CommentKind::Block);
+            assert_eq!(stripped.as_str(), "     a\n");
+        })
+    }
+}