panache_parser/parser/inlines/

citations.rs

//! Citation parsing for Pandoc's citations extension.
//!
//! Syntax:
//! - Bracketed: `[@doe99]`, `[@doe99; @smith2000]`
//! - With locator: `[see @doe99, pp. 33-35]`
//! - Suppress author: `[-@doe99]`
//! - Author-in-text: `@doe99` (bare, without brackets)

use super::sink::InlineSink;
use crate::syntax::SyntaxKind;

/// Try to parse a bracketed citation starting at the current position.
/// Returns Some((length, content)) if successful, None otherwise.
///
/// Bracketed citations have the syntax: [@key], [@key1; @key2], [see @key, pp. 1-10]
pub(crate) fn try_parse_bracketed_citation(text: &str) -> Option<(usize, &str)> {
    let bytes = text.as_bytes();

    // Must start with [
    if bytes.is_empty() || bytes[0] != b'[' {
        return None;
    }

    // Look ahead to see if this contains a citation marker (@)
    // We need to distinguish from regular links
    let mut has_citation = false;
    let mut pos = 1;
    let mut bracket_depth = 0;

    while pos < bytes.len() {
        match bytes[pos] {
            b'\\' => {
                // Skip escaped character
                pos += 2;
                continue;
            }
            b'`' => {
                // Skip verbatim code spans; markers inside don't count.
                match code_span_end(bytes, pos) {
                    Some(end) => pos = end,
                    None => pos += 1,
                }
            }
            b'[' => {
                bracket_depth += 1;
                pos += 1;
            }
            b']' => {
                if bracket_depth == 0 {
                    // Closing bracket of main citation - stop looking
                    break;
                }
                bracket_depth -= 1;
                pos += 1;
                // A nested bracket group directly followed by `(dest)` is an
                // inline link/image; its destination is verbatim, so `@`
                // inside it must not count (pandoc parses
                // `[![alt](https://x.io/@scope)](url)` as a link, not a
                // citation).
                if pos < bytes.len()
                    && bytes[pos] == b'('
                    && let Some(end) = inline_destination_end(bytes, pos)
                {
                    pos = end;
                }
            }
            b'@' => {
                // Found a citation marker - this is likely a citation
                has_citation = true;
                break;
            }
            _ => {
                pos += 1;
            }
        }
    }

    if !has_citation {
        return None;
    }

    // Now find the closing bracket
    pos = 1;
    bracket_depth = 1;

    while pos < bytes.len() {
        match bytes[pos] {
            b'\\' => {
                // Skip escaped character
                pos += 2;
                continue;
            }
            b'`' => {
                // Skip verbatim code spans; brackets inside don't close.
                match code_span_end(bytes, pos) {
                    Some(end) => pos = end,
                    None => pos += 1,
                }
            }
            b'[' => {
                bracket_depth += 1;
                pos += 1;
            }
            b']' => {
                bracket_depth -= 1;
                if bracket_depth == 0 {
                    // Found the closing bracket
                    let content = &text[1..pos];
                    return Some((pos + 1, content));
                }
                pos += 1;
                // Skip nested link/image destinations so a `]` inside them
                // does not terminate the citation bracket.
                if pos < bytes.len()
                    && bytes[pos] == b'('
                    && let Some(end) = inline_destination_end(bytes, pos)
                {
                    pos = end;
                }
            }
            _ => {
                pos += 1;
            }
        }
    }

    // No closing bracket found
    None
}

/// Try to parse a bare citation (author-in-text) starting at the current position.
/// Returns Some((length, key, has_suppress)) if successful, None otherwise.
///
/// Bare citations have the syntax: @key or -@key
pub(crate) fn try_parse_bare_citation(text: &str) -> Option<(usize, &str, bool)> {
    let bytes = text.as_bytes();

    if bytes.is_empty() {
        return None;
    }

    let mut pos = 0;
    let has_suppress = bytes[pos] == b'-';

    if has_suppress {
        pos += 1;
        if pos >= bytes.len() {
            return None;
        }
    }

    // Must have @ next
    if bytes[pos] != b'@' {
        return None;
    }
    pos += 1;

    if pos >= bytes.len() {
        return None;
    }

    // Parse the citation key
    let key_start = pos;
    let key_len = parse_citation_key(&text[pos..])?;

    if key_len == 0 {
        return None;
    }

    let total_len = pos + key_len;
    let key = &text[key_start..total_len];

    Some((total_len, key, has_suppress))
}

/// Try to parse a Quarto cross-reference key (e.g., @fig-plot, @eq-energy).
pub fn is_quarto_crossref_key(key: &str) -> bool {
    let lower = key.to_ascii_lowercase();
    let mut parts = lower.splitn(2, '-');
    let prefix = parts.next().unwrap_or("");
    let rest = parts.next().unwrap_or("");
    if rest.is_empty() {
        return false;
    }
    matches!(
        prefix,
        "fig"
            | "tbl"
            | "lst"
            | "tip"
            | "nte"
            | "wrn"
            | "imp"
            | "cau"
            | "thm"
            | "lem"
            | "cor"
            | "prp"
            | "cnj"
            | "def"
            | "exm"
            | "exr"
            | "sol"
            | "rem"
            | "alg"
            | "eq"
            | "sec"
    )
}

/// Like [`is_quarto_crossref_key`], but also accepts any key whose prefix
/// appears in `custom_prefixes`. Used to recognize cross-reference prefixes
/// injected by Quarto extensions (e.g. pseudocode's `@algo-`) that aren't
/// built in. Matching is case-insensitive on the prefix, consistent with the
/// built-in check.
pub fn is_crossref_key(key: &str, custom_prefixes: &[String]) -> bool {
    is_quarto_crossref_key(key) || has_custom_crossref_prefix(key, custom_prefixes)
}

/// Whether `key`'s prefix (the segment before the first `-`) appears in
/// `custom_prefixes`. Unlike [`is_quarto_crossref_key`], this matches *only*
/// the configured extension prefixes, so callers can tell an extension-injected
/// cross-reference (whose target panache can't resolve) apart from a built-in
/// one (whose target it can and should validate).
pub fn has_custom_crossref_prefix(key: &str, custom_prefixes: &[String]) -> bool {
    if custom_prefixes.is_empty() {
        return false;
    }
    let lower = key.to_ascii_lowercase();
    let mut parts = lower.splitn(2, '-');
    let prefix = parts.next().unwrap_or("");
    let rest = parts.next().unwrap_or("");
    if rest.is_empty() {
        return false;
    }
    custom_prefixes
        .iter()
        .any(|candidate| candidate.eq_ignore_ascii_case(prefix))
}

pub const BOOKDOWN_LABEL_PREFIXES: &[&str] = &[
    "eq", "fig", "tab", "thm", "lem", "cor", "prp", "cnj", "def", "exm", "exr", "sol", "rem",
    "alg", "sec", "hyp",
];

pub fn is_bookdown_label(label: &str) -> bool {
    BOOKDOWN_LABEL_PREFIXES.contains(&label)
}

pub fn has_bookdown_prefix(label: &str) -> bool {
    let mut parts = label.splitn(2, ':');
    let prefix = parts.next().unwrap_or("");
    let rest = parts.next().unwrap_or("");
    if rest.is_empty() {
        return false;
    }
    is_bookdown_label(prefix)
}

pub(crate) fn emit_crossref(builder: &mut impl InlineSink, key: &str, has_suppress: bool) {
    builder.start_node(SyntaxKind::CROSSREF.into());

    if has_suppress {
        builder.token(SyntaxKind::CROSSREF_MARKER.into(), "-@");
    } else {
        builder.token(SyntaxKind::CROSSREF_MARKER.into(), "@");
    }

    if key.starts_with('{') && key.ends_with('}') {
        builder.token(SyntaxKind::CROSSREF_BRACE_OPEN.into(), "{");
        builder.token(SyntaxKind::CROSSREF_KEY.into(), &key[1..key.len() - 1]);
        builder.token(SyntaxKind::CROSSREF_BRACE_CLOSE.into(), "}");
    } else {
        builder.token(SyntaxKind::CROSSREF_KEY.into(), key);
    }

    builder.finish_node();
}

pub(crate) fn emit_bookdown_crossref(builder: &mut impl InlineSink, key: &str) {
    builder.start_node(SyntaxKind::CROSSREF.into());
    builder.token(SyntaxKind::CROSSREF_BOOKDOWN_OPEN.into(), "\\@ref(");
    builder.token(SyntaxKind::CROSSREF_KEY.into(), key);
    builder.token(SyntaxKind::CROSSREF_BOOKDOWN_CLOSE.into(), ")");
    builder.finish_node();
}

/// Parse a citation key following Pandoc's rules.
/// Returns the length of the key, or None if invalid.
///
/// Citation keys:
/// - Must start with letter, digit, or _
/// - Can contain alphanumerics and single internal punctuation: :.#$%&-+?<>~/
/// - Keys in braces @{...} can contain anything
/// - Double internal punctuation terminates key
/// - Trailing punctuation not included
fn parse_citation_key(text: &str) -> Option<usize> {
    if text.is_empty() {
        return None;
    }

    // Check for braced key: @{...}
    if text.starts_with('{') {
        // Find matching closing brace
        let mut escape_next = false;

        for (idx, ch) in text.char_indices().skip(1) {
            if escape_next {
                escape_next = false;
                continue;
            }

            match ch {
                '\\' => escape_next = true,
                '}' => return Some(idx + ch.len_utf8()),
                _ => {}
            }
        }

        // No closing brace found
        return None;
    }

    // Regular key: must start with letter, digit, or _
    let mut iter = text.char_indices();
    let (_, first_char) = iter.next()?;
    if !first_char.is_alphanumeric() && first_char != '_' {
        return None;
    }

    let mut last_alnum_end = first_char.len_utf8();
    let mut last_included_end = last_alnum_end;
    let mut last_punct_start: Option<usize> = None;
    let mut prev_was_punct = false;

    for (idx, ch) in iter {
        if ch.is_alphanumeric() || ch == '_' {
            prev_was_punct = false;
            last_alnum_end = idx + ch.len_utf8();
            last_included_end = last_alnum_end;
            last_punct_start = None;
        } else if is_internal_punctuation(ch) {
            // Check if previous was also punctuation (double punct terminates)
            if prev_was_punct {
                // Double punctuation - terminate before the first punctuation
                return Some(last_punct_start.unwrap_or(last_alnum_end));
            }
            prev_was_punct = true;
            last_punct_start = Some(idx);
            last_included_end = idx + ch.len_utf8();
        } else {
            // Not a valid key character - terminate here
            break;
        }
    }

    if prev_was_punct {
        return Some(last_alnum_end);
    }

    if last_included_end == 0 {
        None
    } else {
        Some(last_included_end)
    }
}

/// If `bytes[pos]` begins a backtick code-span opener, return the index just
/// past the matching closing run. Returns `None` when there is no closing run
/// of equal length, in which case the backticks are literal text.
///
/// Code spans are verbatim, so citation markers (`@`), separators (`;`), and
/// brackets (`]`) inside them must not influence citation detection — this
/// matches pandoc, which parses `` [`@foo`] `` as a link, not a citation.
fn code_span_end(bytes: &[u8], pos: usize) -> Option<usize> {
    let mut open_end = pos;
    while open_end < bytes.len() && bytes[open_end] == b'`' {
        open_end += 1;
    }
    let run = open_end - pos;

    let mut i = open_end;
    while i < bytes.len() {
        if bytes[i] == b'`' {
            let close_start = i;
            while i < bytes.len() && bytes[i] == b'`' {
                i += 1;
            }
            if i - close_start == run {
                return Some(i);
            }
        } else {
            i += 1;
        }
    }

    None
}

/// Given `bytes[pos] == b'('` immediately after a `]` that closed a nested
/// bracket group, return the index just past the closing `)` when the group
/// parses like an inline link/image destination: an optional angle-bracketed
/// or bare (space-free, balanced-paren) destination followed by an optional
/// quoted title. Returns `None` when the group is not destination-shaped, in
/// which case its bytes stay visible to citation detection.
fn inline_destination_end(bytes: &[u8], pos: usize) -> Option<usize> {
    let mut i = pos + 1;
    while i < bytes.len() && matches!(bytes[i], b' ' | b'\t') {
        i += 1;
    }
    if i < bytes.len() && bytes[i] == b'<' {
        // Angle-bracketed destination: runs to the closing `>`.
        i += 1;
        while i < bytes.len() && bytes[i] != b'>' {
            i += if bytes[i] == b'\\' { 2 } else { 1 };
        }
        if i >= bytes.len() {
            return None;
        }
        i += 1;
    } else {
        // Bare destination: no whitespace, balanced parens. A `]` is allowed
        // here (pandoc links `[x](a]b)`).
        let mut depth = 0usize;
        while i < bytes.len() {
            match bytes[i] {
                b'\\' => i += 2,
                b'(' => {
                    depth += 1;
                    i += 1;
                }
                b')' if depth == 0 => break,
                b')' => {
                    depth -= 1;
                    i += 1;
                }
                b' ' | b'\t' | b'\n' => break,
                _ => i += 1,
            }
        }
    }
    // Optional whitespace, which must introduce a quoted title or end the
    // group; a bare space inside the parens is not a valid destination.
    let mut j = i;
    while j < bytes.len() && matches!(bytes[j], b' ' | b'\t' | b'\n') {
        j += 1;
    }
    if j < bytes.len() && (bytes[j] == b'"' || bytes[j] == b'\'') {
        let quote = bytes[j];
        j += 1;
        while j < bytes.len() && bytes[j] != quote {
            j += if bytes[j] == b'\\' { 2 } else { 1 };
        }
        if j >= bytes.len() {
            return None;
        }
        j += 1;
        while j < bytes.len() && matches!(bytes[j], b' ' | b'\t' | b'\n') {
            j += 1;
        }
    }
    (j < bytes.len() && bytes[j] == b')').then(|| j + 1)
}

/// Check if a character is valid internal punctuation in citation keys.
fn is_internal_punctuation(ch: char) -> bool {
    matches!(
        ch,
        ':' | '.' | '#' | '$' | '%' | '&' | '-' | '+' | '?' | '<' | '>' | '~' | '/'
    )
}

/// Emit a bracketed citation node to the builder.
pub(crate) fn emit_bracketed_citation(builder: &mut impl InlineSink, content: &str) {
    builder.start_node(SyntaxKind::CITATION.into());

    // Opening bracket
    builder.token(SyntaxKind::LINK_START.into(), "[");

    // Emit prefix + citations + suffix with fine-grained tokens.
    emit_bracketed_citation_content(builder, content);

    // Closing bracket
    builder.token(SyntaxKind::LINK_DEST.into(), "]");

    builder.finish_node();
}

fn emit_bracketed_citation_content(builder: &mut impl InlineSink, content: &str) {
    let mut text_start = 0;
    let mut iter = content.char_indices().peekable();

    while let Some((idx, ch)) = iter.next() {
        // Backslash escapes (e.g. `\@`, `\[`, `\]`) suppress citation/separator
        // recognition for the following character — matching Pandoc, which
        // treats the escape as a literal in the citation prefix/suffix.
        if ch == '\\' {
            iter.next();
            continue;
        }

        if ch == '`'
            && let Some(end) = code_span_end(content.as_bytes(), idx)
        {
            // Verbatim code span: leave its bytes in the pending
            // CITATION_CONTENT run and skip markers/separators inside it.
            while matches!(iter.peek(), Some((next_idx, _)) if *next_idx < end) {
                iter.next();
            }
            continue;
        }

        if ch == '@' || (ch == '-' && matches!(iter.peek(), Some((_, '@')))) {
            if idx > text_start {
                builder.token(
                    SyntaxKind::CITATION_CONTENT.into(),
                    &content[text_start..idx],
                );
            }

            let mut marker_len = 1;
            let marker_text = if ch == '-' {
                iter.next();
                marker_len = 2;
                "-@"
            } else {
                "@"
            };
            builder.token(SyntaxKind::CITATION_MARKER.into(), marker_text);

            let key_start = idx + marker_len;
            if key_start >= content.len() {
                text_start = key_start;
                continue;
            }

            if let Some(key_len) = parse_citation_key(&content[key_start..]) {
                let key_end = key_start + key_len;
                let key = &content[key_start..key_end];
                if key.starts_with('{') && key.ends_with('}') {
                    builder.token(SyntaxKind::CITATION_BRACE_OPEN.into(), "{");
                    if key.len() > 2 {
                        builder.token(SyntaxKind::CITATION_KEY.into(), &key[1..key.len() - 1]);
                    }
                    builder.token(SyntaxKind::CITATION_BRACE_CLOSE.into(), "}");
                } else {
                    builder.token(SyntaxKind::CITATION_KEY.into(), key);
                }
                while matches!(iter.peek(), Some((next_idx, _)) if *next_idx < key_end) {
                    iter.next();
                }
                text_start = key_end;
                continue;
            }

            text_start = key_start;
            continue;
        }

        if ch == ';' {
            if idx > text_start {
                builder.token(
                    SyntaxKind::CITATION_CONTENT.into(),
                    &content[text_start..idx],
                );
            }
            builder.token(SyntaxKind::CITATION_SEPARATOR.into(), ";");
            text_start = idx + ch.len_utf8();
            continue;
        }
    }

    if text_start < content.len() {
        builder.token(SyntaxKind::CITATION_CONTENT.into(), &content[text_start..]);
    }
}

/// Emit a bare citation node to the builder.
pub(crate) fn emit_bare_citation(builder: &mut impl InlineSink, key: &str, has_suppress: bool) {
    builder.start_node(SyntaxKind::CITATION.into());

    // Emit marker (@ or -@)
    if has_suppress {
        builder.token(SyntaxKind::CITATION_MARKER.into(), "-@");
    } else {
        builder.token(SyntaxKind::CITATION_MARKER.into(), "@");
    }

    // Check if key is braced
    if key.starts_with('{') && key.ends_with('}') {
        builder.token(SyntaxKind::CITATION_BRACE_OPEN.into(), "{");
        builder.token(SyntaxKind::CITATION_KEY.into(), &key[1..key.len() - 1]);
        builder.token(SyntaxKind::CITATION_BRACE_CLOSE.into(), "}");
    } else {
        builder.token(SyntaxKind::CITATION_KEY.into(), key);
    }

    builder.finish_node();
}

#[cfg(test)]
mod tests {
    use super::*;

    // Citation key parsing tests
    #[test]
    fn test_parse_simple_citation_key() {
        assert_eq!(parse_citation_key("doe99"), Some(5));
        assert_eq!(parse_citation_key("smith2000"), Some(9));
    }

    #[test]
    fn test_parse_citation_key_with_internal_punct() {
        assert_eq!(parse_citation_key("Foo_bar.baz"), Some(11));
        assert_eq!(parse_citation_key("author:2020"), Some(11));
    }

    #[test]
    fn test_parse_citation_key_trailing_punct() {
        // Trailing punctuation should be excluded
        assert_eq!(parse_citation_key("Foo_bar.baz."), Some(11));
        assert_eq!(parse_citation_key("key:value:"), Some(9));
    }

    #[test]
    fn test_parse_citation_key_double_punct() {
        // Double punctuation terminates key
        assert_eq!(parse_citation_key("Foo_bar--baz"), Some(7)); // key is "Foo_bar"
    }

    #[test]
    fn test_parse_citation_key_with_braces() {
        assert_eq!(parse_citation_key("{https://example.com}"), Some(21));
        assert_eq!(parse_citation_key("{Foo_bar.baz.}"), Some(14));
    }

    #[test]
    fn test_parse_citation_key_invalid_start() {
        assert_eq!(parse_citation_key(".invalid"), None);
        assert_eq!(parse_citation_key(":invalid"), None);
    }

    #[test]
    fn test_parse_citation_key_stops_at_space() {
        assert_eq!(parse_citation_key("key rest"), Some(3));
    }

    #[test]
    fn is_crossref_key_accepts_builtin_without_custom() {
        assert!(is_crossref_key("fig-plot", &[]));
        assert!(!is_crossref_key("algo-cd", &[]));
    }

    #[test]
    fn is_crossref_key_accepts_custom_prefix() {
        let custom = vec!["algo".to_string()];
        assert!(is_crossref_key("algo-cd", &custom));
        // Case-insensitive on the prefix, consistent with the built-in check.
        assert!(is_crossref_key("ALGO-cd", &custom));
        // Built-ins still match alongside the custom set.
        assert!(is_crossref_key("tbl-x", &custom));
        // A bare prefix with no `-suffix` is not a crossref.
        assert!(!is_crossref_key("algo", &custom));
        // Unrelated prefixes remain citations.
        assert!(!is_crossref_key("doe99", &custom));
    }

    // Bare citation parsing tests
    #[test]
    fn test_parse_bare_citation_simple() {
        let result = try_parse_bare_citation("@doe99");
        assert_eq!(result, Some((6, "doe99", false)));
    }

    #[test]
    fn test_parse_bare_citation_with_suppress() {
        let result = try_parse_bare_citation("-@smith04");
        assert_eq!(result, Some((9, "smith04", true)));
    }

    #[test]
    fn test_parse_bare_citation_with_trailing_text() {
        let result = try_parse_bare_citation("@doe99 says");
        assert_eq!(result, Some((6, "doe99", false)));
    }

    #[test]
    fn test_parse_bare_citation_braced_key() {
        let result = try_parse_bare_citation("@{https://example.com}");
        assert_eq!(result, Some((22, "{https://example.com}", false)));
    }

    #[test]
    fn test_parse_bare_citation_not_citation() {
        assert_eq!(try_parse_bare_citation("not a citation"), None);
        assert_eq!(try_parse_bare_citation("@"), None);
    }

    // Bracketed citation parsing tests
    #[test]
    fn test_parse_bracketed_citation_simple() {
        let result = try_parse_bracketed_citation("[@doe99]");
        assert_eq!(result, Some((8, "@doe99")));
    }

    #[test]
    fn test_parse_bracketed_citation_multiple() {
        let result = try_parse_bracketed_citation("[@doe99; @smith2000]");
        assert_eq!(result, Some((20, "@doe99; @smith2000")));
    }

    #[test]
    fn test_parse_bracketed_citation_with_prefix() {
        let result = try_parse_bracketed_citation("[see @doe99]");
        assert_eq!(result, Some((12, "see @doe99")));
    }

    #[test]
    fn test_parse_bracketed_citation_with_locator() {
        let result = try_parse_bracketed_citation("[@doe99, pp. 33-35]");
        assert_eq!(result, Some((19, "@doe99, pp. 33-35")));
    }

    #[test]
    fn test_parse_bracketed_citation_complex() {
        let result = try_parse_bracketed_citation("[see @doe99, pp. 33-35 and *passim*]");
        assert_eq!(result, Some((36, "see @doe99, pp. 33-35 and *passim*")));
    }

    #[test]
    fn test_parse_bracketed_citation_with_suppress() {
        let result = try_parse_bracketed_citation("[-@doe99]");
        assert_eq!(result, Some((9, "-@doe99")));
    }

    #[test]
    fn test_parse_bracketed_citation_not_citation() {
        // Regular link should not be parsed as citation
        assert_eq!(try_parse_bracketed_citation("[text](url)"), None);
        assert_eq!(try_parse_bracketed_citation("[just text]"), None);
    }

    #[test]
    fn test_parse_bracketed_citation_nested_brackets() {
        let result = try_parse_bracketed_citation("[see [nested] @doe99]");
        assert_eq!(result, Some((21, "see [nested] @doe99")));
    }

    #[test]
    fn test_parse_bracketed_citation_escaped_bracket() {
        let result = try_parse_bracketed_citation(r"[@doe99 with \] escaped]");
        assert_eq!(result, Some((24, r"@doe99 with \] escaped")));
    }

    #[test]
    fn test_parse_bracketed_citation_paren_in_prefix() {
        // Pandoc treats parens in the citation prefix as ordinary text;
        // they must not abort citation detection.
        let result = try_parse_bracketed_citation("[see (Smith 1999) and @doe99]");
        assert_eq!(result, Some((29, "see (Smith 1999) and @doe99")));
    }

    #[test]
    fn test_bracketed_citation_ignores_at_in_code_span() {
        // `@foo` inside a code span is verbatim, so [`@foo`] is a link label,
        // not a citation (matches pandoc).
        assert_eq!(try_parse_bracketed_citation("[`@foo`]"), None);
    }

    #[test]
    fn test_bracketed_citation_code_span_in_prefix() {
        // A code span may appear in the citation prefix; @ inside it is verbatim
        // and the real @key follows.
        assert_eq!(
            try_parse_bracketed_citation("[`x@y` @doe99]"),
            Some((14, "`x@y` @doe99"))
        );
    }

    #[test]
    fn test_bracketed_citation_bracket_in_code_span() {
        // A `]` inside a code span does not terminate the bracket.
        assert_eq!(
            try_parse_bracketed_citation("[`a]b` @doe99]"),
            Some((14, "`a]b` @doe99"))
        );
    }

    #[test]
    fn test_bracketed_citation_unterminated_backtick() {
        // An unterminated backtick run is literal, so @foo is still a citation.
        assert_eq!(
            try_parse_bracketed_citation("[`@foo bar]"),
            Some((11, "`@foo bar"))
        );
    }

    #[test]
    fn test_bracketed_citation_ignores_at_in_nested_image_url() {
        // The @ lives in the image destination, so the outer bracket is a link
        // label, not a citation (matches pandoc's Link [ Image ... ] parse).
        assert_eq!(
            try_parse_bracketed_citation(
                "[![npm version](https://badge.fury.io/js/@arity-cli%2Farity-cli.svg?icon=si%3Anpm)]"
            ),
            None
        );
    }

    #[test]
    fn test_bracketed_citation_ignores_at_in_nested_link_url() {
        assert_eq!(
            try_parse_bracketed_citation("[a [link](https://x.io/@scope) here]"),
            None
        );
    }

    #[test]
    fn test_bracketed_citation_marker_after_nested_link_url() {
        // A nested link's destination is skipped, but a top-level @key after
        // it still makes the bracket a citation (matches pandoc).
        assert_eq!(
            try_parse_bracketed_citation("[see [foo](url@x) and @bar]"),
            Some((27, "see [foo](url@x) and @bar"))
        );
    }

    #[test]
    fn test_parse_bracketed_citation_escaped_at_in_prefix() {
        // Pandoc accepts \@ref(label) inside the citation prefix without
        // mistaking it for a citation marker; the actual citation is the
        // unescaped @key that follows.
        let result =
            try_parse_bracketed_citation(r"[see also \@ref(svm) and @bischl_applied_2024]");
        assert_eq!(
            result,
            Some((46, r"see also \@ref(svm) and @bischl_applied_2024"))
        );
    }
}