perf(formatter): optimize jsdoc formatting to reduce allocations and redundant work

- Hoist FormatOptions clone in format_embedded_js (1 clone instead of up to 4)
- Pre-build type-formatter options once per comment instead of per tag
- Cache type_name_comment() results in reorder_param_tags (1 parse vs 4 per tag)
- Add single-group fast path in sort_tags_by_groups (skip Vec-of-Vec)
- Replace FxHashSet<usize> with SmallVec<[usize; 4]> for import indices
- Add lazy allocation in normalize_markdown_emphasis via dry-run scan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Dunqing

Cargo.lock

@@ -36,6 +36,7 @@ natord = { workspace = true }
 nodejs-built-in-modules = { workspace = true }
 phf = { workspace = true, features = ["macros"] }
 rustc-hash = { workspace = true }
+smallvec = { workspace = true }
 unicode-width = { workspace = true }
 
 [dev-dependencies]

crates/oxc_formatter/Cargo.toml

@@ -41,14 +41,19 @@ pub fn normalize_markdown_emphasis(text: &str) -> Cow<'_, str> {
         return Cow::Borrowed(text);
     }
 
+    // Read-only scan: check if any emphasis change would actually occur,
+    // avoiding a heap allocation when `*` or `__` appear only inside code spans.
+    if !emphasis_needs_change(text.as_bytes()) {
+        return Cow::Borrowed(text);
+    }
+
     // Work with bytes directly — all significant chars (_, *, `, whitespace)
     // are ASCII single-byte, so byte-level mutation is safe and uses ~3x less
     // memory than Vec<char>.
     let mut bytes: Vec<u8> = text.as_bytes().to_vec();
     let len = bytes.len();
     let mut i = 0;
     let mut in_code = false;
-    let mut changed = false;
 
     // First pass: convert `__` → `**`
     while i < len {
@@ -64,7 +69,6 @@ pub fn normalize_markdown_emphasis(text: &str) -> Cow<'_, str> {
         if bytes[i] == b'_' && i + 1 < len && bytes[i + 1] == b'_' {
             bytes[i] = b'*';
             bytes[i + 1] = b'*';
-            changed = true;
             i += 2;
             continue;
         }
@@ -119,7 +123,6 @@ pub fn normalize_markdown_emphasis(text: &str) -> Cow<'_, str> {
                 if bytes[j] == b'*' && j > opener + 1 && !bytes[j - 1].is_ascii_whitespace() {
                     bytes[opener] = b'_';
                     bytes[j] = b'_';
-                    changed = true;
                     i = j + 1;
                     break;
                 }
@@ -134,15 +137,89 @@ pub fn normalize_markdown_emphasis(text: &str) -> Cow<'_, str> {
         i += 1;
     }
 
-    // If no bytes were actually modified, return the original text without allocation.
-    if !changed {
-        return Cow::Borrowed(text);
-    }
     // We only replaced ASCII bytes (_, *) with other ASCII bytes (*, _),
     // so UTF-8 validity is preserved.
     Cow::Owned(String::from_utf8(bytes).unwrap())
 }
 
+/// Read-only scan that checks whether `normalize_markdown_emphasis` would
+/// actually change any bytes. Runs the same two-pass logic without mutation.
+fn emphasis_needs_change(bytes: &[u8]) -> bool {
+    let len = bytes.len();
+    let mut i = 0;
+    let mut in_code = false;
+
+    // Pass 1: would any `__` outside code be converted to `**`?
+    while i < len {
+        if bytes[i] == b'`' {
+            in_code = !in_code;
+            i += 1;
+            continue;
+        }
+        if in_code {
+            i += 1;
+            continue;
+        }
+        if bytes[i] == b'_' && i + 1 < len && bytes[i + 1] == b'_' {
+            return true;
+        }
+        i += 1;
+    }
+
+    // Pass 2: would any single `*text*` outside code be converted to `_text_`?
+    // After pass 1, `__` would become `**`, so `**` sequences need to be skipped.
+    // Since we're read-only, `__` is still `__` — but the mutation pass would have
+    // converted it. We simulate that by also skipping `__` as if it were `**`.
+    in_code = false;
+    i = 0;
+    while i < len {
+        if bytes[i] == b'`' {
+            in_code = !in_code;
+            i += 1;
+            continue;
+        }
+        if in_code {
+            i += 1;
+            continue;
+        }
+        // Skip `**` and `__` (which would become `**` after pass 1)
+        if (bytes[i] == b'*' || bytes[i] == b'_') && i + 1 < len && bytes[i + 1] == bytes[i] {
+            i += 2;
+            continue;
+        }
+        // Single `*` — check for matching closing emphasis
+        if bytes[i] == b'*' && i + 1 < len && !bytes[i + 1].is_ascii_whitespace() {
+            let opener = i;
+            let mut j = opener + 1;
+            while j < len {
+                if bytes[j] == b'`' {
+                    j += 1;
+                    while j < len && bytes[j] != b'`' {
+                        j += 1;
+                    }
+                    if j < len {
+                        j += 1;
+                    }
+                    continue;
+                }
+                if bytes[j] == b'*' && j + 1 < len && bytes[j + 1] == b'*' {
+                    j += 2;
+                    continue;
+                }
+                if bytes[j] == b'*' && j > opener + 1 && !bytes[j - 1].is_ascii_whitespace() {
+                    return true;
+                }
+                j += 1;
+            }
+            i = opener + 1;
+            continue;
+        }
+        i += 1;
+    }
+
+    false
+}
+
 /// Capitalize the first ASCII lowercase letter of a string.
 /// Skips if the string starts with a backtick (inline code) or a URL.
 /// Handles `"- "` prefix iteratively: `"- - hello"` → `"- - Hello"` with a single allocation.

crates/oxc_formatter/src/formatter/jsdoc/normalize.rs

@@ -220,41 +220,45 @@ fn reorder_param_tags(
         return;
     }
 
-    // Check that ALL @param tags have type annotations and names
     let param_tags = &effective_tags[param_start..param_end];
-    let has_all_types_and_names = param_tags.iter().all(|(tag, _)| {
-        let (type_part, name_part, _) = tag.type_name_comment();
-        type_part.is_some() && name_part.is_some()
-    });
-    if !has_all_types_and_names {
-        return; // Some params lack types or names — don't reorder
+
+    // Parse type_name_comment() once per tag, cache the results.
+    // Each call does O(n) brace-counting, and we'd otherwise call it 4x per tag.
+    let parsed: Vec<_> = param_tags
+        .iter()
+        .map(|(tag, _)| {
+            let (type_part, name_part, _) = tag.type_name_comment();
+            (type_part.is_some(), name_part.map(|n| n.parsed()))
+        })
+        .collect();
+
+    // Check that ALL @param tags have type annotations and names
+    if !parsed.iter().all(|(has_type, name)| *has_type && name.is_some()) {
+        return;
     }
 
+    // Extract the cached names (we verified all are Some above)
+    let names: Vec<&str> = parsed.iter().map(|(_, name)| name.unwrap_or("")).collect();
+
     // Extract function parameter names from the source text after the comment
     let fn_params = extract_function_params(comment, source_text);
-    if fn_params.len() != param_tags.len() {
+    if fn_params.len() != names.len() {
         return;
     }
 
     // Already in order?
-    if param_tags.iter().zip(fn_params.iter()).all(|((tag, _), p)| {
-        let (_, name_part, _) = tag.type_name_comment();
-        name_part.map_or("", |n| n.parsed()) == *p
-    }) {
+    if names.iter().zip(fn_params.iter()).all(|(name, p)| *name == *p) {
         return;
     }
 
     // Check same set of names (lengths already verified equal, param lists are small)
-    if !param_tags.iter().all(|(tag, _)| {
-        let (_, name_part, _) = tag.type_name_comment();
-        let name = name_part.map_or("", |n| n.parsed());
-        fn_params.contains(&name)
-    }) {
+    if !names.iter().all(|name| fn_params.contains(name)) {
         return;
     }
 
-    // Sort @param tags by their position in the function signature
-    effective_tags[param_start..param_end].sort_by_key(|(tag, _)| {
+    // Sort @param tags by their position in the function signature.
+    // Use sort_by_cached_key to call the key function once per element.
+    effective_tags[param_start..param_end].sort_by_cached_key(|(tag, _)| {
         let (_, name_part, _) = tag.type_name_comment();
         let name = name_part.map_or("", |n| n.parsed());
         fn_params.iter().position(|p| *p == name).unwrap_or(usize::MAX)
@@ -616,23 +620,46 @@ fn sort_tags_by_groups<'a>(
         return Vec::new();
     }
 
-    // Split into groups at TAGS_GROUP_HEAD boundaries, but only when a
+    // Build normalized list once (avoids calling normalize_tag_kind twice per tag).
+    let mut normalized: Vec<(&oxc_jsdoc::parser::JSDocTag<'a>, &'a str)> =
+        tags.iter().map(|tag| (tag, normalize_tag_kind(tag.kind.parsed()))).collect();
+
+    // Fast path: check if any group split is actually needed.
+    // A split only occurs when a TAGS_GROUP_HEAD appears after a TAGS_GROUP_CONDITION.
+    let mut needs_split = false;
+    let mut seen_condition = false;
+    for &(_, kind) in &normalized {
+        if is_tags_group_condition(kind) {
+            seen_condition = true;
+        }
+        if is_tags_group_head(kind) && seen_condition {
+            needs_split = true;
+            break;
+        }
+    }
+
+    if !needs_split {
+        // Single group — sort in-place, no Vec-of-Vec overhead
+        normalized.sort_by_key(|(_, kind)| tag_sort_priority(kind));
+        return normalized;
+    }
+
+    // Multi-group path: split at TAGS_GROUP_HEAD boundaries when a
     // TAGS_GROUP_CONDITION tag has been seen first (matching upstream behavior).
     let mut groups: Vec<Vec<(&oxc_jsdoc::parser::JSDocTag<'a>, &'a str)>> = Vec::new();
     let mut current_group: Vec<(&oxc_jsdoc::parser::JSDocTag<'a>, &'a str)> = Vec::new();
     let mut can_group_next_tags = false;
 
-    for tag in tags {
-        let normalized_kind = normalize_tag_kind(tag.kind.parsed());
-        if is_tags_group_head(normalized_kind) && can_group_next_tags && !current_group.is_empty() {
+    for (tag, kind) in normalized {
+        if is_tags_group_head(kind) && can_group_next_tags && !current_group.is_empty() {
             groups.push(current_group);
             current_group = Vec::new();
             can_group_next_tags = false;
         }
-        if is_tags_group_condition(normalized_kind) {
+        if is_tags_group_condition(kind) {
             can_group_next_tags = true;
         }
-        current_group.push((tag, normalized_kind));
+        current_group.push((tag, kind));
     }
     if !current_group.is_empty() {
         groups.push(current_group);
@@ -762,6 +789,10 @@ pub fn format_jsdoc_comment<'a>(
     // Reorder @param tags to match the function signature order
     reorder_param_tags(&mut effective_tags, comment, source_text);
 
+    // Pre-build FormatOptions for type formatting — avoids cloning the full
+    // FormatOptions (which contains heap Vecs) per tag.
+    let type_format_options = FormatOptions { jsdoc: None, ..format_options.clone() };
+
     // Pre-process @import tags: merge by module, sort, format
     let (mut import_lines, parsed_import_indices) = process_import_tags(&effective_tags);
     let has_imports = !import_lines.is_empty();
@@ -860,7 +891,7 @@ pub fn format_jsdoc_comment<'a>(
                 wrap_width,
                 has_no_space_before_type,
                 bracket_spacing,
-                format_options,
+                &type_format_options,
                 external_callbacks,
                 &mut content_lines,
             );
@@ -872,7 +903,7 @@ pub fn format_jsdoc_comment<'a>(
                 wrap_width,
                 has_no_space_before_type,
                 bracket_spacing,
-                format_options,
+                &type_format_options,
                 external_callbacks,
                 &mut content_lines,
             );
@@ -1362,9 +1393,9 @@ pub(super) fn format_embedded_js(
     let width = u16::try_from(print_width).unwrap_or(80).clamp(1, 320);
     let line_width = LineWidth::try_from(width).unwrap();
 
-    // Build options from parent, overriding line_width and disabling JSDoc
-    // to prevent recursive formatting
-    let make_options = || FormatOptions { line_width, jsdoc: None, ..format_options.clone() };
+    // Clone once upfront — subsequent clones of base_options are cheap since
+    // the Vec fields (sort_imports, sort_tailwindcss) are already owned.
+    let base_options = FormatOptions { line_width, jsdoc: None, ..format_options.clone() };
 
     // Try to parse and format with the given source type
     let try_format = |code: &str, source_type: SourceType| -> Option<String> {
@@ -1374,7 +1405,7 @@ pub(super) fn format_embedded_js(
         if ret.panicked || !ret.errors.is_empty() {
             return None;
         }
-        let mut formatted = Formatter::new(&allocator, make_options()).build(&ret.program);
+        let mut formatted = Formatter::new(&allocator, base_options.clone()).build(&ret.program);
         truncate_trim_end(&mut formatted);
         Some(formatted)
     };
@@ -1393,6 +1424,10 @@ pub(super) fn format_embedded_js(
     let trimmed = code.trim();
     if trimmed.starts_with('{') {
         let wrapped = format!("({trimmed})");
+        // Use TrailingCommas::None for object literals since JSON-like code
+        // shouldn't have trailing commas
+        let obj_options =
+            FormatOptions { trailing_commas: TrailingCommas::None, ..base_options.clone() };
 
         let try_format_obj = |code: &str, source_type: SourceType| -> Option<String> {
             let allocator = Allocator::default();
@@ -1402,10 +1437,7 @@ pub(super) fn format_embedded_js(
             if ret.panicked || !ret.errors.is_empty() {
                 return None;
             }
-            // Use TrailingCommas::None for object literals since JSON-like code
-            // shouldn't have trailing commas
-            let options = FormatOptions { trailing_commas: TrailingCommas::None, ..make_options() };
-            let formatted = Formatter::new(&allocator, options).build(&ret.program);
+            let formatted = Formatter::new(&allocator, obj_options.clone()).build(&ret.program);
             let formatted = formatted.trim_end();
             // Remove the wrapping parens and trailing semicolon
             if let Some(inner) = formatted.strip_prefix('(')
@@ -1460,8 +1492,9 @@ fn format_type_via_formatter(type_str: &str, format_options: &FormatOptions) ->
     let input = format!("type __t = {type_str};");
 
     let allocator = Allocator::default();
-    let line_width = format_options.line_width;
-    let options = FormatOptions { line_width, jsdoc: None, ..format_options.clone() };
+    // The caller is expected to pass pre-built options with jsdoc: None.
+    // Clone is cheap here since the expensive Vec fields are already owned.
+    let options = format_options.clone();
 
     let ret = Parser::new(&allocator, &input, SourceType::tsx())
         .with_options(get_parse_options())
@@ -2468,9 +2501,9 @@ fn format_import_lines(import: &ImportInfo, content_lines: &mut Vec<String>) {
 /// `@import` tags can fall through to `format_generic_tag()`).
 fn process_import_tags(
     tags: &[(&oxc_jsdoc::parser::JSDocTag<'_>, &str)],
-) -> (Vec<String>, rustc_hash::FxHashSet<usize>) {
+) -> (Vec<String>, smallvec::SmallVec<[usize; 4]>) {
     let mut imports = Vec::new();
-    let mut parsed_indices = rustc_hash::FxHashSet::default();
+    let mut parsed_indices = smallvec::SmallVec::<[usize; 4]>::new();
 
     for (idx, &(tag, kind)) in tags.iter().enumerate() {
         if kind != "import" {
@@ -2479,7 +2512,7 @@ fn process_import_tags(
         let comment = tag.comment().parsed();
         if let Some(info) = parse_import_tag(&comment) {
             imports.push(info);
-            parsed_indices.insert(idx);
+            parsed_indices.push(idx);
         }
     }