Use shared primitives for docstring backticks

Author: lerebear

crates/ty_ide/src/docstring/document/syntax.rs

@@ -62,56 +62,13 @@ pub(in crate::docstring) fn starts_with_markdown_list_item(line: &str) -> bool {
 ///
 /// For example, this returns `true` for ``"`value`"`` and `false` for
 /// ``"`value` trailing"``.
-pub(in crate::docstring) fn is_markdown_code_span(text: &str) -> bool {
-    find_backtick_run(text, TextSize::ZERO).and_then(|opening| markdown_code_span(text, opening))
-        == Some(TextRange::up_to(TextSize::of(text)))
-}
-
-/// Returns the byte range of the first consecutive backtick run at or after `from`.
-///
-/// For example, searching ``"value `code`"`` from the start returns the range covering the
-/// opening ``"`"``.
-pub(in crate::docstring) fn find_backtick_run(text: &str, from: TextSize) -> Option<TextRange> {
-    let from = from.to_usize();
-    let start = from + text.get(from..)?.find('`')?;
-    let len = text[start..]
-        .bytes()
-        .take_while(|byte| *byte == b'`')
-        .count();
-    Some(TextRange::new(
-        TextSize::of(&text[..start]),
-        TextSize::of(&text[..start + len]),
-    ))
-}
-
-/// Returns the Markdown code span delimited by `opening`, if it has a matching closing run.
-///
-/// For example, the opening run in "``value`with:ticks`` trailing" produces the range covering
-/// "``value`with:ticks``".
-pub(in crate::docstring) fn markdown_code_span(
-    text: &str,
-    opening: TextRange,
-) -> Option<TextRange> {
-    let mut search_from = opening.end();
-    loop {
-        let closing = find_backtick_run(text, search_from)?;
-        if closing.len() == opening.len() {
-            return Some(opening.cover(closing));
-        }
-        search_from = closing.end();
-    }
-}
+pub(crate) fn is_markdown_code_span(text: &str) -> bool {
+    let mut fragments = BacktickFragments::new(text);
+    let Some(BacktickFragment::Span(_)) = fragments.next() else {
+        return false;
+    };
 
-/// Returns whether the backtick run at `index` is escaped by a preceding backslash.
-///
-/// For example, the backtick in ``"\`"`` is escaped, while the backtick in ``"\\`"`` is not.
-pub(in crate::docstring) fn is_backtick_run_escaped(text: &str, index: usize) -> bool {
-    !text[..index]
-        .bytes()
-        .rev()
-        .take_while(|byte| *byte == b'\\')
-        .count()
-        .is_multiple_of(2)
+    fragments.next().is_none()
 }
 
 /// Losslessly partitions source text around complete, unescaped backtick spans.
@@ -155,33 +112,29 @@ impl<'a> Iterator for BacktickFragments<'a> {
     type Item = BacktickFragment<'a>;
 
     fn next(&mut self) -> Option<Self::Item> {
-        if self.last_fragment_end == TextSize::of(self.scanner.source) {
-            return None;
-        }
-
-        let span = loop {
+        let span = if let Some(span) = self.pending_span.take() {
             // Emit the span saved while returning its preceding text on the previous call.
-            if let Some(span) = self.pending_span.take() {
-                break span;
-            }
-
-            // Without another backtick run, the remaining source is all plain text.
-            let Some(opening) = self.scanner.next() else {
-                return self.take_remaining_text();
-            };
+            span
+        } else {
+            loop {
+                // Without another backtick run, the remaining source is all plain text.
+                let Some(opening) = self.scanner.next() else {
+                    return self.take_remaining_text();
+                };
+
+                // Escaped runs are literal source text, so continue looking for the next possible
+                // opening without emitting a fragment boundary.
+                if opening.is_escaped() {
+                    continue;
+                }
 
-            // Escaped runs are literal source text, so continue looking for the next possible
-            // opening without emitting a fragment boundary.
-            if opening.is_escaped() {
-                continue;
+                // Without a closing delimiter, callers cannot treat the opening or any later runs as
+                // structured markup. Emit the remainder as one text fragment.
+                let Some(span) = self.scanner.eat_span(opening) else {
+                    return self.take_remaining_text();
+                };
+                break span;
             }
-
-            // Without a closing delimiter, callers cannot treat the opening or any later runs as
-            // structured markup. Emit the remainder as one text fragment.
-            let Some(span) = self.scanner.eat_span(opening) else {
-                return self.take_remaining_text();
-            };
-            break span;
         };
 
         if self.last_fragment_end < span.start() {
@@ -329,11 +282,6 @@ impl<'a> BacktickScanner<'a> {
             delimiter_len: opening.range.len(),
         })
     }
-
-    /// Returns the scanner's cursor at its current position.
-    pub(in crate::docstring) fn into_cursor(self) -> Cursor<'a> {
-        self.cursor
-    }
 }
 
 impl Iterator for BacktickScanner<'_> {
@@ -514,28 +462,41 @@ pub(super) fn split_trailing_parenthetical(value: &str) -> Option<(&str, &str)>
     let mut outermost_opening = None;
     let mut cursor = Cursor::new(value);
 
-    while let Some(character) = cursor.bump() {
-        let index = cursor.offset().to_usize() - character.len_utf8();
+    loop {
+        let start = cursor.offset();
+        let Some(character) = cursor.bump() else {
+            break;
+        };
+
         match character {
-            '\'' | '"' => consume_quoted_string(&mut cursor, character),
-            '`' if !is_backtick_run_escaped(value, index) => {
-                let opening = find_backtick_run(value, TextSize::of(&value[..index]))?;
-                let span = markdown_code_span(value, opening).unwrap_or(opening);
-                cursor.skip_bytes((span.end() - cursor.offset()).to_usize());
+            quote @ ('\'' | '"') => consume_quoted_string(&mut cursor, quote),
+            '`' => {
+                let mut scanner = BacktickScanner::starts_at(start, value);
+                let opening = scanner.next()?;
+                if opening.is_escaped() {
+                    // The loop has consumed only the first, escaped backtick. Leave the rest of
+                    // the run for the next iteration, where it may open a shorter span.
+                    continue;
+                }
+
+                let end = scanner
+                    .eat_span(opening)
+                    .map_or_else(|| opening.end(), |span| span.end());
+                cursor.skip_bytes((end - cursor.offset()).to_usize());
             }
             '(' => {
                 if depth == 0 {
-                    outermost_opening = Some(index);
+                    outermost_opening = Some(start);
                 }
                 depth += 1;
             }
             ')' => {
                 depth = depth.checked_sub(1)?;
                 if depth == 0 && cursor.is_eof() {
                     let opening = outermost_opening?;
-                    let prefix = value[..opening].trim();
-                    let contents = value[opening + '('.len_utf8()..index].trim();
-                    return Some((prefix, contents));
+                    let (prefix, parenthetical) = value.split_at(opening.to_usize());
+                    let contents = parenthetical.strip_prefix('(')?.strip_suffix(')')?;
+                    return Some((prefix.trim(), contents.trim()));
                 }
             }
             _ => {}
@@ -576,7 +537,7 @@ mod tests {
         let span = scanner.eat_span(opening).expect("a matching backtick run");
         assert!(!span.is_single());
         assert_eq!(span.content(), "code");
-        assert_eq!(scanner.into_cursor().as_str(), " suffix");
+        assert_eq!(scanner.as_str(), " suffix");
     }
 
     #[test]
@@ -700,6 +661,22 @@ mod tests {
         );
     }
 
+    #[test]
+    fn ignores_parentheses_inside_code_spans_after_escaped_backtick() {
+        assert_eq!(
+            split_trailing_parenthetical(r"value (\``)`)"),
+            Some(("value", r"\``)`"))
+        );
+    }
+
+    #[test]
+    fn treats_unmatched_backticks_as_plain_parenthetical_text() {
+        assert_eq!(
+            split_trailing_parenthetical("value (`unfinished)"),
+            Some(("value", "`unfinished"))
+        );
+    }
+
     #[test]
     fn ignores_parentheses_after_escaped_quotes() {
         assert_eq!(

crates/ty_ide/src/docstring/markdown/general/inline.rs

@@ -49,11 +49,9 @@
 
 use std::borrow::Cow;
 
-use ruff_text_size::TextSize;
+use ruff_text_size::{Ranged, TextSize};
 
-use crate::docstring::document::syntax::{
-    find_backtick_run, is_backtick_run_escaped, markdown_code_span,
-};
+use crate::docstring::document::syntax::BacktickScanner;
 
 /// Exposes an interface for rendering a line of prose that may contain a hyperlink.
 #[derive(Default)]
@@ -278,28 +276,26 @@ enum Candidate<'a> {
 
 /// Finds the first complete hyperlink or plausible wrapped candidate in `input`.
 fn find_link(input: &str) -> Option<(usize, Candidate<'_>)> {
-    let mut offset = TextSize::ZERO;
+    let mut scanner = BacktickScanner::new(input);
 
     // Visit each backtick run that could delimit inline markup.
-    while let Some(run) = find_backtick_run(input, offset) {
+    while let Some(run) = scanner.next() {
         let index = run.start().to_usize();
 
         // An escaped run is literal text, so continue immediately after it.
-        if is_backtick_run_escaped(input, index) {
-            offset = run.end();
+        if run.is_escaped() {
             continue;
         }
 
-        // Try parsing a link only when a single backtick has valid surrounding characters.
-        if run.len() == TextSize::new(1)
-            && is_link_start(input, index)
+        // Try parsing a link only when the backtick run has valid surrounding characters.
+        if is_link_start(input, index)
             && let Some(candidate) = parse_candidate(&input[index..])
         {
             return Some((index, candidate));
         }
 
         // Skip other backtick-delimited spans rather than searching inside them.
-        offset = markdown_code_span(input, run)?.end();
+        scanner.eat_span(run)?;
     }
 
     None
@@ -310,7 +306,13 @@ fn find_link(input: &str) -> Option<(usize, Candidate<'_>)> {
 /// Plausible wrapped labels without a closing backtick remain pending;
 /// malformed or unsupported forms return `None`.
 fn parse_candidate(input: &str) -> Option<Candidate<'_>> {
-    let after_opening = input.strip_prefix('`')?;
+    let mut scanner = BacktickScanner::new(input);
+    let opening = scanner.next()?;
+    if opening.start() != TextSize::ZERO {
+        return None;
+    }
+
+    let after_opening = scanner.as_str();
     if after_opening
         .chars()
         .next()
@@ -319,7 +321,11 @@ fn parse_candidate(input: &str) -> Option<Candidate<'_>> {
         return None;
     }
 
-    let Some(closing) = find_backtick_run(input, TextSize::new(1)) else {
+    let Some(closing) = scanner.next() else {
+        if !opening.is_single() {
+            return None;
+        }
+
         // Eliminate candidates whose content already contains a disallowed
         // backslash or closing `>`, or whose target cannot become HTTP(S). A
         // partial URI scheme remains valid so it can wrap immediately after
@@ -333,21 +339,22 @@ fn parse_candidate(input: &str) -> Option<Candidate<'_>> {
         }
         return Some(Candidate::Pending);
     };
-    if closing.len() != TextSize::new(1) {
+    let span = scanner.span(opening, closing)?;
+    if !span.is_single() {
         return None;
     }
 
-    let content = &input[1..closing.start().to_usize()];
+    let content = span.content();
     if content.contains('\\') {
         return None;
     }
 
-    let after_closing = &input[closing.end().to_usize()..];
+    let after_closing = scanner.as_str();
     let underscore_count = after_closing
         .bytes()
         .take_while(|byte| *byte == b'_')
         .count();
-    let len = closing.end().to_usize() + underscore_count;
+    let len = span.end().to_usize() + underscore_count;
     if !(1..=2).contains(&underscore_count) || !is_link_suffix(&after_closing[underscore_count..]) {
         return None;
     }