rumdl_lib/lint_context/

mod.rs

pub mod types;
pub(crate) use heading_detection::is_paragraph_text_line;
pub(crate) use link_parser::{image_pattern, link_pattern};
pub use types::*;

mod bracket_math;
mod element_parsers;
mod flavor_detection;
mod heading_detection;
mod line_computation;
mod link_parser;
mod list_blocks;
mod mdx;
#[cfg(test)]
mod tests;

use crate::config::MarkdownFlavor;
use crate::inline_config::InlineConfig;
use crate::rules::front_matter_utils::FrontMatterUtils;
use crate::utils::code_block_utils::{CodeBlockDetail, CodeBlockUtils};
use crate::utils::range_utils::byte_to_char_count;
use std::collections::HashMap;
use std::ops::Range;
use std::path::{Path, PathBuf};

/// Run-scoped document paths that filesystem-aware link rules should treat as
/// present even when their content did not come from disk.
#[derive(Debug, Clone)]
pub struct LinkTargetPolicy {
    supplied_paths: Arc<std::collections::HashSet<PathBuf>>,
    /// Every directory that holds a supplied path, at any depth. A supplied
    /// set implies its directories the way a git index does, so a link to one
    /// resolves without consulting disk.
    supplied_dirs: Arc<std::collections::HashSet<PathBuf>>,
    allow_disk_fallback: bool,
}

impl LinkTargetPolicy {
    /// Supplied documents override disk, while targets outside the supplied set
    /// continue to use normal filesystem resolution.
    pub fn open_world<I, P>(paths: I) -> Self
    where
        I: IntoIterator<Item = P>,
        P: AsRef<Path>,
    {
        Self::from_paths(paths, true)
    }

    /// Only supplied documents are valid relative link targets.
    pub fn closed_world<I, P>(paths: I) -> Self
    where
        I: IntoIterator<Item = P>,
        P: AsRef<Path>,
    {
        Self::from_paths(paths, false)
    }

    fn from_paths<I, P>(paths: I, allow_disk_fallback: bool) -> Self
    where
        I: IntoIterator<Item = P>,
        P: AsRef<Path>,
    {
        let mut roots = Vec::new();
        if let Ok(cwd) = std::env::current_dir() {
            if let Ok(canonical_cwd) = cwd.canonicalize()
                && canonical_cwd != cwd
            {
                roots.push(canonical_cwd);
            }
            roots.push(cwd);
        }
        Self::from_paths_with_roots(paths, allow_disk_fallback, roots)
    }

    fn from_paths_with_roots<I, P, R, Q>(paths: I, allow_disk_fallback: bool, roots: R) -> Self
    where
        I: IntoIterator<Item = P>,
        P: AsRef<Path>,
        R: IntoIterator<Item = Q>,
        Q: AsRef<Path>,
    {
        let roots: Vec<PathBuf> = roots
            .into_iter()
            .map(|root| crate::workspace_index::normalize_relative_path(root.as_ref()))
            .collect();
        let mut supplied_paths = std::collections::HashSet::new();
        for path in paths {
            let path = path.as_ref();
            supplied_paths.insert(crate::workspace_index::normalize_relative_path(path));

            if path.is_relative() {
                for root in &roots {
                    supplied_paths.insert(crate::workspace_index::normalize_relative_path(&root.join(path)));
                }
            } else {
                // An absolute path inside a working root is also that root's
                // relative path, the spelling a link from a relatively
                // supplied document resolves to. It can reach the root through
                // a symlinked ancestor (`/var` for `/private/var`), so it is
                // also read through its deepest existing ancestor.
                let resolved = crate::discovery::resolve_for_matching(path);
                let relative = [path, resolved.as_path()].into_iter().find_map(|spelling| {
                    roots
                        .iter()
                        .find_map(|source_root| spelling.strip_prefix(source_root).ok())
                });
                if let Some(relative) = relative {
                    supplied_paths.insert(crate::workspace_index::normalize_relative_path(relative));
                    for root in &roots {
                        supplied_paths.insert(crate::workspace_index::normalize_relative_path(&root.join(relative)));
                    }
                }
            }
        }
        // Collected from the normalized paths, so directories are compared
        // component by component: `doc` never matches a supplied `docs/b.md`.
        // A relative path's last ancestor is the empty path, which is how the
        // working root itself normalizes (`./`, or `../` from one level down).
        // Nothing above a working root is implied: a root's own parents hold
        // the batch but are not part of it. Paths that escape every working
        // root share one root of their own, the deepest directory that holds
        // them all, computed separately for absolute and relative spellings.
        let escapes_roots = |path: &Path| {
            if path.is_absolute() {
                !roots.iter().any(|root| path.starts_with(root))
            } else {
                path.starts_with("..")
            }
        };
        let outside_root = |absolute: bool| {
            supplied_paths
                .iter()
                .filter(|path| path.is_absolute() == absolute && escapes_roots(path))
                .filter_map(|path| path.parent())
                .fold(None::<&Path>, |common, dir| {
                    Some(common.map_or(dir, |common| {
                        common
                            .ancestors()
                            .find(|ancestor| dir.starts_with(ancestor))
                            .unwrap_or(common)
                    }))
                })
        };
        let outside_roots = [outside_root(true), outside_root(false)];
        let supplied_dirs = supplied_paths
            .iter()
            .flat_map(|path| path.ancestors().skip(1))
            .filter(|dir| {
                !escapes_roots(dir)
                    || outside_roots
                        .iter()
                        .flatten()
                        .any(|outside_root| dir.starts_with(outside_root))
            })
            .map(Path::to_path_buf)
            .collect();
        Self {
            supplied_paths: Arc::new(supplied_paths),
            supplied_dirs: Arc::new(supplied_dirs),
            allow_disk_fallback,
        }
    }

    pub fn contains(&self, path: &Path) -> bool {
        self.supplied_paths
            .contains(&crate::workspace_index::normalize_relative_path(path))
    }

    pub(crate) fn resolve_supplied(&self, path: &Path) -> Option<PathBuf> {
        let normalized = crate::workspace_index::normalize_relative_path(path);
        if self.supplied_paths.contains(&normalized) {
            return Some(normalized);
        }

        if path.extension().is_none() {
            for extension in ["md", "markdown", "mdx", "mkd", "mkdn", "mdown", "mdwn", "qmd", "rmd"] {
                let candidate = crate::workspace_index::normalize_relative_path(&path.with_extension(extension));
                if self.supplied_paths.contains(&candidate) {
                    return Some(candidate);
                }
            }
        }

        // Tried last, so `docs` names a supplied `docs.md` before the
        // directory. A directory gets no extension fallback.
        if self.supplied_dirs.contains(&normalized) {
            return Some(normalized);
        }

        None
    }

    pub fn contains_with_markdown_extension(&self, path: &Path) -> bool {
        self.resolve_supplied(path).is_some()
    }

    pub fn allow_disk_fallback(&self) -> bool {
        self.allow_disk_fallback
    }
}

/// Macro for profiling sections - only active in non-WASM builds
#[cfg(not(target_arch = "wasm32"))]
macro_rules! profile_section {
    ($name:expr, $profile:expr, $code:expr) => {{
        let start = std::time::Instant::now();
        let result = $code;
        if $profile {
            eprintln!("[PROFILE] {}: {:?}", $name, start.elapsed());
        }
        result
    }};
}

fn build_commonmark_ordered_lists(
    lines: &[LineInfo],
    line_to_list: &crate::utils::code_block_utils::LineToListMap,
    list_start_values: &crate::utils::code_block_utils::ListStartValues,
) -> Vec<CommonMarkOrderedListInfo> {
    let mut grouped_lines: HashMap<usize, Vec<usize>> = HashMap::new();

    for (&line_num, &list_id) in line_to_list {
        let is_ordered_item = line_num
            .checked_sub(1)
            .and_then(|index| lines.get(index))
            .and_then(|line| line.list_item.as_deref())
            .is_some_and(|item| item.is_ordered);
        if is_ordered_item {
            grouped_lines.entry(list_id).or_default().push(line_num);
        }
    }

    let mut lists: Vec<_> = grouped_lines
        .into_iter()
        .map(|(list_id, mut item_lines)| {
            item_lines.sort_unstable();
            CommonMarkOrderedListInfo {
                start_value: list_start_values.get(&list_id).copied().unwrap_or(1),
                item_lines,
            }
        })
        .collect();
    lists.sort_by_key(|list| list.item_lines.first().copied().unwrap_or(0));
    lists
}

#[cfg(target_arch = "wasm32")]
macro_rules! profile_section {
    ($name:expr, $profile:expr, $code:expr) => {{ $code }};
}

/// Grouped byte ranges for skip context detection
/// Used to reduce parameter count in internal functions
pub(super) struct SkipByteRanges<'a> {
    pub(super) html_comment_ranges: &'a [crate::utils::skip_context::ByteRange],
    pub(super) autodoc_ranges: &'a [crate::utils::skip_context::ByteRange],
    pub(super) pandoc_div_ranges: &'a [crate::utils::skip_context::ByteRange],
    pub(super) pymdown_block_ranges: &'a [crate::utils::skip_context::ByteRange],
}

use std::sync::{Arc, OnceLock};

/// Map from line byte offset to list item data: (is_ordered, marker, marker_column, content_column, number)
pub(super) type ListItemMap = std::collections::HashMap<usize, (bool, String, usize, usize, Option<usize>)>;

/// Type alias for byte ranges used in JSX expression and MDX comment detection
pub(super) type ByteRanges = Vec<(usize, usize)>;

pub struct LintContext<'a> {
    pub content: &'a str,
    content_lines: Vec<&'a str>, // Pre-split lines from content (avoids repeated allocations)
    pub line_offsets: Vec<usize>,
    pub code_blocks: Vec<(usize, usize)>, // Cached code block ranges (not including inline code spans)
    pub code_block_details: Vec<CodeBlockDetail>, // Per-block metadata (fenced/indented, info string)
    pub strong_spans: Vec<crate::utils::code_block_utils::StrongSpanDetail>, // Pre-computed strong emphasis spans
    line_to_list: crate::utils::code_block_utils::LineToListMap, // Private CommonMark membership input
    list_start_values: crate::utils::code_block_utils::ListStartValues, // Private CommonMark start-value input
    definition_lists: DefinitionListLines, // Parser-detected definition lists, in lines
    commonmark_ordered_lists_cache: OnceLock<Vec<CommonMarkOrderedListInfo>>, // Lazy source-ordered view
    pub lines: Vec<LineInfo>,             // Pre-computed line information
    blockquote_headings: Vec<Option<Box<HeadingInfo>>>, // Container headings, parallel to `lines`
    links: Vec<ParsedLink<'a>>,           // Pre-parsed links
    images: Vec<ParsedImage<'a>>,         // Pre-parsed images
    broken_links: Vec<BrokenLinkInfo>,    // Broken/undefined references
    footnote_refs: Vec<FootnoteRef>,      // Pre-parsed footnote references
    reference_defs: Vec<ReferenceDef>,    // Reference definitions
    reference_defs_map: HashMap<String, usize>, // O(1) lookup by lowercase ID -> index in reference_defs
    code_spans_cache: OnceLock<Arc<Vec<CodeSpan>>>, // Lazy-loaded inline code spans
    math_spans_cache: OnceLock<Arc<Vec<MathSpan>>>, // Lazy-loaded math spans ($...$ and $$...$$)
    bracket_math_cache: OnceLock<bracket_math::BracketDisplayMathLines>,
    math_byte_ranges_cache: OnceLock<Vec<(usize, usize)>>, // Lazy-loaded math byte ranges for is_in_math_context
    pub list_blocks: Vec<ListBlock>,                       // Pre-parsed list blocks
    pub char_frequency: CharFrequency,                     // Character frequency analysis
    html_tags_cache: OnceLock<Arc<Vec<HtmlTag>>>,          // Lazy-loaded HTML tags
    jsx_component_tags_cache: OnceLock<Arc<Vec<HtmlTag>>>, // Lazy-loaded JSX component tags (shares the html_tags parse)
    emphasis_spans_cache: OnceLock<Arc<Vec<EmphasisSpan>>>, // Lazy-loaded emphasis spans
    bare_urls_cache: OnceLock<Arc<Vec<BareUrl>>>,          // Lazy-loaded bare URLs
    has_mixed_list_nesting_cache: OnceLock<bool>, // Cached result for mixed ordered/unordered list nesting detection
    html_comment_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed HTML comment ranges
    pub table_blocks: Vec<crate::utils::table_utils::TableBlock>, // Pre-computed table blocks
    line_index: crate::utils::range_utils::LineIndex<'a>, // Pre-computed source-location index
    jinja_ranges: Vec<(usize, usize)>,            // Pre-computed Jinja template ranges ({{ }}, {% %})
    pub flavor: MarkdownFlavor,                   // Markdown flavor being used
    source_file: Option<PathBuf>,                 // Source file path (capability exposed through `source_file()`)
    link_target_policy: Option<LinkTargetPolicy>, // Run-scoped virtual link targets
    invalid_utf8: Option<&'a [crate::encoding::InvalidSeq]>, // Set only for lossily decoded input
    jsx_expression_ranges: Vec<(usize, usize)>,   // Pre-computed JSX expression ranges (MDX: {expression})
    mdx_comment_ranges: Vec<(usize, usize)>,      // Pre-computed MDX comment ranges ({/* ... */})
    citation_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc/Quarto citation ranges (@key, [@key])
    pandoc_div_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc/Quarto div block ranges (::: ... :::)
    colon_fence_details: Vec<CodeBlockDetail>, // Pre-computed Azure DevOps colon code fences (:::lang ... :::)
    inline_footnote_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc inline footnote ranges (^[...])
    pandoc_header_slugs: std::collections::HashSet<String>, // Pre-computed Pandoc implicit header reference slugs
    example_list_marker_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc example-list marker ranges (@) / (@label)
    example_reference_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc example reference ranges (@label) inline
    sub_super_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc subscript (~x~) and superscript (^x^) ranges
    inline_code_attr_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc inline code attribute ranges (`code`{.lang})
    bracketed_span_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc bracketed span ranges ([text]{attrs})
    line_block_ranges: Vec<crate::utils::skip_context::ByteRange>,     // Pre-computed Pandoc line block ranges (| text)
    pipe_table_caption_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc pipe-table caption ranges (: caption)
    pandoc_metadata_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc YAML metadata block ranges (--- ... --- or ...)
    grid_table_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc grid-table ranges (+---+---+)
    multi_line_table_ranges: Vec<crate::utils::skip_context::ByteRange>, // Pre-computed Pandoc multi-line table ranges
    shortcode_ranges: Vec<(usize, usize)>, // Pre-computed Hugo/Quarto shortcode ranges ({{< ... >}} and {{% ... %}})
    link_title_ranges: Vec<(usize, usize)>, // Pre-computed sorted link title byte ranges
    code_span_byte_ranges: Vec<(usize, usize)>, // Pre-computed code span byte ranges from pulldown-cmark
    inline_config: InlineConfig,           // Parsed inline configuration comments for rule disabling
    obsidian_comment_ranges: Vec<(usize, usize)>, // Pre-computed Obsidian comment ranges (%%...%%)
    unterminated_html_comment: Option<usize>, // Byte offset of a `<!--` with no `-->`
    unterminated_obsidian_comment: Option<usize>, // Byte offset of a `%%` with no closing `%%`
    lazy_cont_lines_cache: OnceLock<Arc<Vec<LazyContLine>>>, // Lazy-loaded lazy continuation lines
    myst_directive_ranges: Vec<(usize, usize)>, // Pre-computed MyST colon directive byte ranges (:::{name} ... :::)
    myst_comment_ranges: Vec<(usize, usize)>, // Pre-computed MyST comment byte ranges (% comment)
    myst_role_ranges: Vec<(usize, usize)>, // Pre-computed MyST role byte ranges ({role}`content`)
    front_matter_end: usize,               // 1-indexed line where front matter ends, 0 if none
}

/// The two kinds of byte range a document holds as code.
pub struct CodeRanges {
    /// Fenced and indented code block ranges
    pub blocks: Vec<(usize, usize)>,
    /// Inline code span ranges, backticks included
    pub spans: Vec<(usize, usize)>,
}

/// The byte ranges this document's flavor really holds as code.
///
/// An inline directive written inside one of these configures nothing, so there
/// is nothing to report about it. The answer is read off a full context rather
/// than scanned out of the text, which is what keeps it identical to the one
/// `InlineConfig` was built from: a MkDocs admonition body is indented but is
/// structure, and a scan of the text alone reads it as an indented code block.
///
/// Building a context costs a parse, so callers filter with it only once they
/// hold something to filter, and both kinds come back from the one parse.
pub fn code_ranges(content: &str, flavor: MarkdownFlavor) -> CodeRanges {
    let ctx = LintContext::new(content, flavor, None);
    CodeRanges {
        spans: code_span_byte_ranges(&ctx.code_spans()),
        blocks: ctx.code_blocks,
    }
}

/// The byte ranges of parsed code spans, as the plain pairs inline config works in.
pub fn code_span_byte_ranges(code_spans: &[CodeSpan]) -> Vec<(usize, usize)> {
    code_spans
        .iter()
        .map(|span| (span.byte_offset, span.byte_end))
        .collect()
}

impl<'a> LintContext<'a> {
    /// The native source path available to filesystem-aware rules.
    ///
    /// Virtual adapters intentionally leave this unset even when they provide a
    /// logical path for configuration matching.
    pub fn source_file(&self) -> Option<&Path> {
        self.source_file.as_deref()
    }

    pub fn link_target_policy(&self) -> Option<&LinkTargetPolicy> {
        self.link_target_policy.as_ref()
    }

    pub fn with_link_target_policy(mut self, policy: LinkTargetPolicy) -> Self {
        self.link_target_policy = Some(policy);
        self
    }

    /// The invalid UTF-8 sequences this content was lossily decoded from, if any.
    pub fn invalid_utf8(&self) -> Option<&'a [crate::encoding::InvalidSeq]> {
        self.invalid_utf8
    }

    pub fn with_invalid_utf8(mut self, invalid: &'a [crate::encoding::InvalidSeq]) -> Self {
        self.invalid_utf8 = Some(invalid);
        self
    }

    pub fn new(content: &'a str, flavor: MarkdownFlavor, source_file: Option<PathBuf>) -> Self {
        #[cfg(not(target_arch = "wasm32"))]
        let profile = std::env::var("RUMDL_PROFILE_QUADRATIC").is_ok();

        let line_offsets = profile_section!("Line offsets", profile, {
            let mut offsets = vec![0];
            for (i, c) in content.char_indices() {
                if c == '\n' {
                    offsets.push(i + 1);
                }
            }
            offsets
        });

        // Compute content_lines once for all functions that need it
        let content_lines: Vec<&str> = content.lines().collect();

        // Detect front matter boundaries once for all functions that need it.
        // This is the single allowed call site; rules read the cached value
        // via front_matter_end_line().
        #[allow(clippy::disallowed_methods)]
        let front_matter_end = FrontMatterUtils::get_front_matter_end_line(content);

        // Detect code blocks and code spans once and cache them
        let parse_result = profile_section!(
            "Code blocks",
            profile,
            CodeBlockUtils::detect_code_blocks_and_spans(content)
        );
        let mut code_blocks = parse_result.code_blocks;
        let mut code_span_ranges = parse_result.code_spans;
        let code_block_details = parse_result.code_block_details;
        let strong_spans = parse_result.strong_spans;
        let line_to_list = parse_result.line_to_list;
        let list_start_values = parse_result.list_start_values;
        let html_blocks = parse_result.html_blocks;
        let definition_lists = DefinitionListLines::new(
            &line_offsets,
            &parse_result.definition_items,
            &parse_result.definition_terms,
            &parse_result.definition_texts,
        );

        // Container structure the parser cannot see. Computed from the line text
        // alone, so it is available here, before the line info it corrects.
        let containers = profile_section!(
            "Container lines",
            profile,
            flavor_detection::detect_container_lines(&content_lines, flavor)
        );

        // Pre-compute HTML comment ranges ONCE for all operations.
        // Code-span and code-block ranges are passed so `<!--`/`-->` inside code
        // are treated as literal text, not comment delimiters that could pair
        // across code regions on different lines. An indented block over
        // container content is the parser reading a MkDocs admonition or a
        // `<div markdown>` body as code, and a comment written there is a real
        // comment, so only the parts of such a block that a fence really does
        // hold as code are kept.
        let comment_code_block_ranges: Vec<(usize, usize)> = code_block_details
            .iter()
            .flat_map(|detail| {
                if detail.is_fenced {
                    return vec![(detail.start, detail.end)];
                }
                let start_line = line_offsets
                    .partition_point(|&offset| offset <= detail.start)
                    .saturating_sub(1);
                let end_line = line_offsets.partition_point(|&offset| offset < detail.end);
                containers
                    .code_line_spans_in(start_line..end_line)
                    .into_iter()
                    .map(|span| {
                        let start = line_offsets[span.start].max(detail.start);
                        let end = line_offsets
                            .get(span.end)
                            .copied()
                            .unwrap_or(content.len())
                            .min(detail.end);
                        (start, end)
                    })
                    .collect()
            })
            .collect();
        // Front matter is data, not markdown: a `<!--` in a YAML value would
        // otherwise pair with a `-->` in the body and hide everything between
        // them from every rule. `front_matter_end` is the 1-indexed closing
        // delimiter line, so the body starts at the line after it, and a
        // document without front matter starts at byte 0.
        let body_start = line_offsets.get(front_matter_end).copied().unwrap_or(content.len());
        let html_comment_scan = profile_section!(
            "HTML comment ranges",
            profile,
            crate::utils::skip_context::scan_html_comments(
                content,
                &code_span_ranges,
                &comment_code_block_ranges,
                body_start
            )
        );
        let mut html_comment_ranges = html_comment_scan.ranges;
        let unterminated_html_comment = html_comment_scan.unterminated;

        // Pre-compute autodoc block ranges (avoids O(n^2) scaling)
        // Detected for all flavors except AzureDevOps, where `:::` denotes code fences
        // rather than autodoc directives.
        let autodoc_ranges = profile_section!("Autodoc block ranges", profile, {
            if flavor.supports_colon_code_fences() || flavor.supports_myst_directives() {
                Vec::new()
            } else {
                crate::utils::mkdocstrings_refs::detect_autodoc_block_ranges(content, flavor)
            }
        });

        // Pre-compute Pandoc/Quarto div block ranges for Pandoc-compatible flavors
        let pandoc_div_ranges = profile_section!("Pandoc div ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_div_block_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute PyMdown Blocks ranges for MkDocs flavor (/// ... ///)
        let pymdown_block_ranges = profile_section!("PyMdown block ranges", profile, {
            if flavor == MarkdownFlavor::MkDocs {
                crate::utils::pymdown_blocks::detect_block_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute line information AND emphasis spans (without headings/blockquotes yet)
        // Emphasis spans are captured during the same pulldown-cmark parse as list detection
        let skip_ranges = SkipByteRanges {
            html_comment_ranges: &html_comment_ranges,
            autodoc_ranges: &autodoc_ranges,
            pandoc_div_ranges: &pandoc_div_ranges,
            pymdown_block_ranges: &pymdown_block_ranges,
        };
        let (mut lines, emphasis_spans) = profile_section!(
            "Basic line info",
            profile,
            line_computation::compute_basic_line_info(
                content,
                &content_lines,
                &line_offsets,
                &code_blocks,
                flavor,
                &skip_ranges,
                front_matter_end,
            )
        );

        // Detect HTML blocks BEFORE heading detection
        profile_section!(
            "HTML blocks",
            profile,
            heading_detection::detect_html_blocks(content, &mut lines)
        );

        // Detect ESM import/export blocks in MDX files BEFORE heading detection
        profile_section!(
            "ESM blocks",
            profile,
            flavor_detection::detect_esm_blocks(content, &mut lines, flavor)
        );

        // Detect JSX component blocks in MDX files (e.g. <Tabs>...</Tabs>)
        profile_section!(
            "JSX block detection",
            profile,
            flavor_detection::detect_jsx_blocks(content, &mut lines, flavor)
        );

        // Detect JSX expressions and MDX comments in MDX files
        let (jsx_expression_ranges, mdx_comment_ranges) = profile_section!(
            "JSX/MDX detection",
            profile,
            flavor_detection::detect_jsx_and_mdx_comments(content, &mut lines, flavor, &code_blocks)
        );

        // Detect `<div markdown>`-style HTML blocks (grid cards, etc.) regardless of flavor.
        // The `markdown` attribute is an explicit, author-supplied signal; recognizing it
        // in all flavors keeps `rumdl fmt` from mangling Material grid cards when the
        // MkDocs flavor isn't active.
        profile_section!(
            "Markdown-in-HTML blocks",
            profile,
            flavor_detection::detect_markdown_html_blocks(&mut lines, &containers)
        );

        let mdx_context = if flavor == MarkdownFlavor::MDX {
            mdx::MdxContext::parse(content, &lines)
        } else {
            None
        };
        let (jsx_expression_ranges, mdx_comment_ranges) = if let Some(mdx) = &mdx_context {
            mdx.apply_lines(&mut lines);
            code_blocks.clone_from(&mdx.code_blocks);
            code_span_ranges.clone_from(&mdx.code_spans);
            (mdx.expressions.clone(), mdx.comments.clone())
        } else {
            (jsx_expression_ranges, mdx_comment_ranges)
        };

        // Detect MkDocs-specific constructs (admonitions, tabs, definition lists)
        profile_section!(
            "MkDocs constructs",
            profile,
            flavor_detection::detect_mkdocs_line_info(&content_lines, &mut lines, flavor, &containers)
        );

        // Detect footnote definitions and correct false code block detection.
        // With ENABLE_FOOTNOTES, pulldown-cmark correctly parses multi-line
        // footnotes, but the code block detector may still mark 4-space-indented
        // footnote continuation lines as indented code blocks.
        profile_section!(
            "Footnote definitions",
            profile,
            detect_footnote_definitions(content, &mut lines, &line_offsets)
        );

        // Filter code_blocks to remove false positives from footnote continuation content.
        // Same pattern as MkDocs/JSX corrections below.
        {
            let mut new_code_blocks = Vec::with_capacity(code_blocks.len());
            for &(start, end) in &code_blocks {
                let start_line = line_offsets
                    .partition_point(|&offset| offset <= start)
                    .saturating_sub(1);
                let end_line = line_offsets.partition_point(|&offset| offset < end).min(lines.len());

                let mut sub_start: Option<usize> = None;
                for (i, &offset) in line_offsets[start_line..end_line]
                    .iter()
                    .enumerate()
                    .map(|(j, o)| (j + start_line, o))
                {
                    let is_real_code = lines.get(i).is_some_and(|info| info.in_code_block);
                    if is_real_code && sub_start.is_none() {
                        let byte_start = if i == start_line { start } else { offset };
                        sub_start = Some(byte_start);
                    } else if !is_real_code && sub_start.is_some() {
                        new_code_blocks.push((sub_start.unwrap(), offset));
                        sub_start = None;
                    }
                }
                if let Some(s) = sub_start {
                    new_code_blocks.push((s, end));
                }
            }
            code_blocks = new_code_blocks;
        }

        // Filter code_blocks to remove false positives from MkDocs admonition/tab content
        // and `<div markdown>` HTML blocks (grid cards).
        // pulldown-cmark treats 4-space-indented content as indented code blocks, but inside
        // these containers this is regular markdown content. detect_mkdocs_line_info and
        // detect_markdown_html_blocks already corrected LineInfo.in_code_block for these lines,
        // but the code_blocks byte ranges are still stale. We split ranges rather than using
        // all-or-nothing removal, so fenced code blocks within the containers are preserved.
        let has_markdown_html = lines.iter().any(|l| l.in_mkdocs_html_markdown);
        if flavor == MarkdownFlavor::MkDocs || has_markdown_html {
            let mut new_code_blocks = Vec::with_capacity(code_blocks.len());
            for &(start, end) in &code_blocks {
                let start_line = line_offsets
                    .partition_point(|&offset| offset <= start)
                    .saturating_sub(1);
                let end_line = line_offsets.partition_point(|&offset| offset < end).min(lines.len());

                // Walk lines in this range, collecting sub-ranges where in_code_block is true
                let mut sub_start: Option<usize> = None;
                for (i, &offset) in line_offsets[start_line..end_line]
                    .iter()
                    .enumerate()
                    .map(|(j, o)| (j + start_line, o))
                {
                    let is_real_code = lines.get(i).is_some_and(|info| info.in_code_block);
                    if is_real_code && sub_start.is_none() {
                        let byte_start = if i == start_line { start } else { offset };
                        sub_start = Some(byte_start);
                    } else if !is_real_code && sub_start.is_some() {
                        new_code_blocks.push((sub_start.unwrap(), offset));
                        sub_start = None;
                    }
                }
                if let Some(s) = sub_start {
                    new_code_blocks.push((s, end));
                }
            }
            code_blocks = new_code_blocks;
        }

        // Filter code_blocks for MDX JSX blocks (same pattern as MkDocs above).
        // detect_jsx_blocks already corrected LineInfo.in_code_block for indented content
        // inside JSX component blocks, but code_blocks byte ranges need updating too.
        if flavor.supports_jsx() {
            let mut new_code_blocks = Vec::with_capacity(code_blocks.len());
            for &(start, end) in &code_blocks {
                let start_line = line_offsets
                    .partition_point(|&offset| offset <= start)
                    .saturating_sub(1);
                let end_line = line_offsets.partition_point(|&offset| offset < end).min(lines.len());

                let mut sub_start: Option<usize> = None;
                for (i, &offset) in line_offsets[start_line..end_line]
                    .iter()
                    .enumerate()
                    .map(|(j, o)| (j + start_line, o))
                {
                    let is_real_code = lines.get(i).is_some_and(|info| info.in_code_block);
                    if is_real_code && sub_start.is_none() {
                        let byte_start = if i == start_line { start } else { offset };
                        sub_start = Some(byte_start);
                    } else if !is_real_code && sub_start.is_some() {
                        new_code_blocks.push((sub_start.unwrap(), offset));
                        sub_start = None;
                    }
                }
                if let Some(s) = sub_start {
                    new_code_blocks.push((s, end));
                }
            }
            code_blocks = new_code_blocks;

            // Add byte ranges for fenced code blocks nested inside a JSX component.
            // pulldown-cmark classifies the whole component as one HTML block and
            // emits no code-block range for the fence, so the split loop above
            // (which can only narrow existing ranges) never adds it. Derive the
            // ranges from the per-line in_code_block flags detect_jsx_blocks set,
            // so byte-range consumers (e.g. MD011, MD044) skip the fence content.
            let mut jsx_fence_ranges: Vec<(usize, usize)> = Vec::new();
            let mut run: Option<(usize, usize)> = None;
            for line in &lines {
                if line.in_jsx_block && line.in_code_block {
                    let line_end = line.byte_offset + line.byte_len;
                    match &mut run {
                        Some((_, end)) => *end = line_end,
                        None => run = Some((line.byte_offset, line_end)),
                    }
                } else if let Some(r) = run.take() {
                    jsx_fence_ranges.push(r);
                }
            }
            if let Some(r) = run.take() {
                jsx_fence_ranges.push(r);
            }
            if !jsx_fence_ranges.is_empty() {
                code_blocks.extend(jsx_fence_ranges);
                code_blocks.sort_by_key(|&(start, _)| start);
            }
        }

        // Detect Azure DevOps colon code fences and extend code_blocks so that
        // all byte-range consumers correctly skip their content.
        let colon_fence_details = profile_section!(
            "Azure colon fence detection",
            profile,
            flavor_detection::detect_azure_colon_fences(content, &mut lines, flavor)
        );
        if !colon_fence_details.is_empty() {
            code_blocks.extend(colon_fence_details.iter().map(|fence| (fence.start, fence.end)));
            code_blocks.sort_by_key(|&(start, _)| start);
        }

        // Detect MyST colon directives (:::{name} ... :::) — these are structural
        // containers, NOT code blocks. Content inside is linted as markdown.
        let myst_directive_ranges = profile_section!(
            "MyST colon directives",
            profile,
            flavor_detection::detect_myst_colon_directives(content, &mut lines, flavor)
        );

        // Detect MyST % comments
        let myst_comment_ranges = profile_section!(
            "MyST comments",
            profile,
            flavor_detection::detect_myst_comments(content, &mut lines, flavor)
        );

        // Detect MyST backtick directives (```{name}) and clear in_code_block for
        // content-bearing directives so their body is linted as markdown.
        profile_section!(
            "MyST backtick directives",
            profile,
            flavor_detection::detect_myst_backtick_directives(
                content,
                &mut lines,
                flavor,
                &code_block_details,
                &line_offsets
            )
        );

        // Filter code_blocks to remove false positives from MyST content-bearing directives.
        // Same pattern as MkDocs admonition filtering.
        if flavor.supports_myst_directives() {
            let mut new_code_blocks = Vec::with_capacity(code_blocks.len());
            for &(start, end) in &code_blocks {
                let start_line = line_offsets
                    .partition_point(|&offset| offset <= start)
                    .saturating_sub(1);
                let end_line = line_offsets.partition_point(|&offset| offset < end).min(lines.len());

                let mut sub_start: Option<usize> = None;
                for (i, &offset) in line_offsets[start_line..end_line]
                    .iter()
                    .enumerate()
                    .map(|(j, o)| (j + start_line, o))
                {
                    let is_real_code = lines.get(i).is_some_and(|info| info.in_code_block);
                    if is_real_code && sub_start.is_none() {
                        let byte_start = if i == start_line { start } else { offset };
                        sub_start = Some(byte_start);
                    } else if !is_real_code && sub_start.is_some() {
                        new_code_blocks.push((sub_start.unwrap(), offset));
                        sub_start = None;
                    }
                }
                if let Some(s) = sub_start {
                    new_code_blocks.push((s, end));
                }
            }
            code_blocks = new_code_blocks;
        }

        // Detect kramdown constructs (extension blocks, IALs, ALDs) in kramdown flavor
        profile_section!(
            "Kramdown constructs",
            profile,
            flavor_detection::detect_kramdown_line_info(content, &mut lines, flavor)
        );

        // Layer 1: Sanitize content-derived fields inside kramdown extension blocks
        // so downstream heading detection and collection builders never see them.
        // This must run BEFORE detect_headings_and_blockquotes to prevent headings
        // from being populated inside extension blocks.
        for line in &mut lines {
            if line.in_kramdown_extension_block {
                line.list_item = None;
                line.is_horizontal_rule = false;
                line.blockquote = None;
                line.is_kramdown_block_ial = false;
            }
        }

        // Detect Obsidian comments (%%...%%) in Obsidian flavor
        let obsidian_comment_scan = profile_section!(
            "Obsidian comments",
            profile,
            flavor_detection::detect_obsidian_comments(
                content,
                &mut lines,
                flavor,
                &code_span_ranges,
                &html_comment_ranges,
                body_start
            )
        );
        let mut obsidian_comment_ranges = obsidian_comment_scan.ranges;
        let mut unterminated_obsidian_comment = obsidian_comment_scan.unterminated;

        // An Obsidian comment hides the text it wraps, so a `<!--` inside one is
        // not a comment opener. The HTML scan cannot know that yet - detecting
        // Obsidian comments needs its ranges - so the opener it reported is
        // re-resolved here, now that the comments that hide it are known.
        let unterminated_html_comment = crate::utils::skip_context::unterminated_html_comment_outside(
            unterminated_html_comment,
            &obsidian_comment_ranges,
            content,
            &code_span_ranges,
            &comment_code_block_ranges,
            body_start,
        );

        // An unclosed `<!--` that opens an HTML block comments out the rest of
        // that block, so the text below it is not content any rule should judge.
        // Without this the block-structure rules and the comment-aware rules
        // disagree about the same lines: the parser reports no list inside the
        // block, while a bare URL there is still flagged.
        //
        // The opener stays reported either way. This governs what the rest of
        // the linter sees, not whether the missing closer is raised.
        //
        // It waits for the re-resolution above because an opener a `%%` pair
        // hides is not an opener, and giving that one a range would hide the
        // rest of the note from every rule.
        if let Some(range) = unterminated_html_comment.and_then(|opener| {
            crate::utils::skip_context::unterminated_comment_range(opener, &html_blocks)
                .or_else(|| container_comment_range(opener, &containers, &lines, content))
        }) {
            // Every complete comment starts before the unclosed opener, so this
            // keeps the ranges sorted for the binary searches over them.
            html_comment_ranges.push(range);

            // The line flags are computed before the Obsidian comments are
            // known, so they predate this range. Recomputing them through the
            // same helper keeps `is_in_html_comment` and the per-line flag
            // answering alike, which is the agreement this range exists to
            // create.
            for line in &mut lines {
                let text = line.content(content);
                let content_start = line.byte_offset + line.indent;
                let content_end = line.byte_offset + text.trim_end().len();
                line.in_html_comment = crate::utils::skip_context::is_line_entirely_in_html_comment(
                    &html_comment_ranges,
                    content_start,
                    content_end,
                );
                line.in_obsidian_comment = false;
            }

            // The `%%` delimiters the block covers are comment text, so a
            // delimiter below the block opens a comment rather than closing the
            // one those appeared to open. Only a rescan pairs them correctly;
            // dropping the ranges that start inside the block would leave the
            // delimiter below it paired with nothing and unreported.
            //
            // This is the mirror of the re-resolution above, and it needs no
            // second round: the block starts at or after the opener, so the
            // pairing before the opener is what it already was, and the opener
            // resolved against it cannot change.
            let obsidian_rescan = flavor_detection::detect_obsidian_comments(
                content,
                &mut lines,
                flavor,
                &code_span_ranges,
                &html_comment_ranges,
                body_start,
            );
            obsidian_comment_ranges = obsidian_rescan.ranges;
            unterminated_obsidian_comment = obsidian_rescan.unterminated;
        }

        // Detect MyST role syntax ({role}`content`)
        let myst_role_ranges = profile_section!(
            "MyST roles",
            profile,
            flavor_detection::detect_myst_role_ranges(content, &lines, flavor, &code_blocks)
        );

        // Run pulldown-cmark parse for links, images, and link byte ranges in a single pass.
        // Link byte ranges are needed for heading detection; links/images are finalized later
        // after code_spans are available.
        let mut pulldown_result = profile_section!(
            "Links, images & link ranges",
            profile,
            link_parser::parse_links_images_pulldown(content, &lines, &code_blocks, flavor, &html_comment_ranges)
        );

        if let Some(mdx) = &mdx_context {
            let (links, images) = mdx.links_and_images(content, &lines);
            pulldown_result.link_byte_ranges = links.iter().map(|link| (link.byte_offset, link.byte_end)).collect();
            pulldown_result.link_found_positions = links.iter().map(|link| link.byte_offset).collect();
            pulldown_result.image_found_positions = images.iter().map(|image| image.byte_offset).collect();
            pulldown_result.links = links;
            pulldown_result.images = images;
            pulldown_result.footnote_refs = mdx.footnote_refs();
            pulldown_result
                .broken_links
                .retain(|link| mdx.contains_text(link.span.start, link.span.end));
        }

        heading_detection::mark_parser_html_blocks(content, &mut lines, &html_blocks, flavor);

        // Now detect headings and blockquotes
        let mdx_flow_lines = mdx_context.as_ref().map(|mdx| mdx.flow_lines(&lines));
        let mut blockquote_headings = profile_section!(
            "Headings & blockquotes",
            profile,
            heading_detection::detect_headings_and_blockquotes(
                &content_lines,
                &mut lines,
                flavor,
                &html_comment_ranges,
                &html_blocks,
                &code_blocks,
                &code_span_ranges,
                &pulldown_result.link_byte_ranges,
                front_matter_end,
                mdx_flow_lines.as_deref(),
            )
        );

        // Clear headings that were detected inside kramdown extension blocks
        for line in &mut lines {
            if line.in_kramdown_extension_block {
                line.heading = None;
            }
        }
        for (line, heading) in lines.iter().zip(&mut blockquote_headings) {
            if line.in_kramdown_extension_block {
                *heading = None;
            }
        }

        // A run of `-`, `*` or `_` is a thematic break only because of the block it
        // sits in, and that block is known only now: the passes above are what mark
        // an HTML comment, an HTML block, a math block, an MDX or Obsidian comment,
        // and the colon fences a flavor reads as code. The flag was computed from the
        // line text before any of them ran, so it is settled here against the answers
        // they produced, the way the kramdown sanitization above settles its own.
        //
        // Left alone deliberately: containers whose body IS markdown (Pandoc divs,
        // MkDocs admonitions and tabs, PyMdown blocks, MyST directives) render a
        // thematic break written in them.
        for line in &mut lines {
            if line.is_horizontal_rule
                && (line.in_code_block
                    || line.in_html_block
                    || line.in_html_comment
                    || line.in_math_block
                    || line.in_mdx_comment
                    || line.in_obsidian_comment)
            {
                line.is_horizontal_rule = false;
            }
        }

        // Parse code spans early so we can exclude them from link/image parsing
        let mut code_spans = profile_section!(
            "Code spans",
            profile,
            element_parsers::build_code_spans_from_ranges(content, &lines, &code_span_ranges)
        );

        // Supplement code spans for MkDocs container content that pulldown-cmark missed.
        // pulldown-cmark treats 4-space-indented MkDocs content as indented code blocks,
        // so backtick code spans within admonitions/tabs/markdown HTML are invisible to it.
        if flavor == MarkdownFlavor::MkDocs {
            let extra = profile_section!(
                "MkDocs code spans",
                profile,
                element_parsers::scan_mkdocs_container_code_spans(content, &lines, &code_span_ranges,)
            );
            if !extra.is_empty() {
                code_spans.extend(extra);
                code_spans.sort_by_key(|span| span.byte_offset);
            }
        }

        // Supplement code spans for MDX JSX component body content that pulldown-cmark missed.
        // pulldown-cmark treats JSX component opening tags (e.g. `<ParamField>`) as HTML block
        // starters, so backtick code spans within component bodies are invisible to the initial
        // parse.
        if flavor == MarkdownFlavor::MDX && mdx_context.is_none() {
            let extra = profile_section!(
                "MDX JSX code spans",
                profile,
                element_parsers::scan_jsx_block_code_spans(content, &lines, &code_span_ranges)
            );
            if !extra.is_empty() {
                code_spans.extend(extra);
                code_spans.sort_by_key(|span| span.byte_offset);
            }
        }

        // Mark lines that are continuations of multi-line code spans
        // This is needed for parse_list_blocks to correctly handle list items with multi-line code spans
        for span in &code_spans {
            if span.end_line > span.line {
                // Mark lines after the first line as continuations
                for line_num in (span.line + 1)..=span.end_line {
                    if let Some(line_info) = lines.get_mut(line_num - 1) {
                        line_info.in_code_span_continuation = true;
                    }
                }
            }
        }

        // Finalize links and images: filter by code_spans and run regex fallbacks
        let (links, images, broken_links, footnote_refs) = profile_section!(
            "Links & images finalize",
            profile,
            link_parser::finalize_links_and_images(
                content,
                &lines,
                flavor,
                &link_parser::LinkExclusions {
                    code_blocks: &code_blocks,
                    code_spans: &code_spans,
                    html_comment_ranges: &html_comment_ranges,
                    mdx: mdx_context.as_ref(),
                },
                pulldown_result,
            )
        );

        let reference_defs = profile_section!("Reference defs", profile, {
            if let Some(mdx) = &mdx_context {
                mdx.reference_defs(content)
            } else {
                link_parser::parse_reference_defs(content, &lines)
            }
        });

        let list_blocks = profile_section!("List blocks", profile, list_blocks::parse_list_blocks(content, &lines));

        // Compute character frequency for fast content analysis
        let char_frequency = profile_section!(
            "Char frequency",
            profile,
            line_computation::compute_char_frequency(content)
        );

        // Pre-compute table blocks for rules that need them (MD013, MD055, MD056, MD058, MD060)
        let table_blocks = profile_section!(
            "Table blocks",
            profile,
            crate::utils::table_utils::TableUtils::find_table_blocks_with_code_info(
                content,
                &code_blocks,
                &code_spans,
                &html_comment_ranges,
                flavor,
            )
        );

        // Layer 2: Filter pre-computed collections to exclude items inside kramdown extension blocks.
        // Rules that iterate these collections automatically skip kramdown content.
        let links = links
            .into_iter()
            .filter(|link| !lines.get(link.line - 1).is_some_and(|l| l.in_kramdown_extension_block))
            .collect::<Vec<_>>();
        let images = images
            .into_iter()
            .filter(|img| !lines.get(img.line - 1).is_some_and(|l| l.in_kramdown_extension_block))
            .collect::<Vec<_>>();
        let broken_links = broken_links
            .into_iter()
            .filter(|bl| {
                // BrokenLinkInfo has span but no line field; find line from byte offset
                let line_idx = line_offsets
                    .partition_point(|&offset| offset <= bl.span.start)
                    .saturating_sub(1);
                !lines.get(line_idx).is_some_and(|l| l.in_kramdown_extension_block)
            })
            .collect::<Vec<_>>();
        let footnote_refs = footnote_refs
            .into_iter()
            .filter(|fr| !lines.get(fr.line - 1).is_some_and(|l| l.in_kramdown_extension_block))
            .collect::<Vec<_>>();
        let reference_defs = reference_defs
            .into_iter()
            .filter(|def| !lines.get(def.line - 1).is_some_and(|l| l.in_kramdown_extension_block))
            .collect::<Vec<_>>();
        let list_blocks = list_blocks
            .into_iter()
            .filter(|block| {
                !lines
                    .get(block.start_line - 1)
                    .is_some_and(|l| l.in_kramdown_extension_block)
            })
            .collect::<Vec<_>>();
        let table_blocks = table_blocks
            .into_iter()
            .filter(|block| {
                // TableBlock.start_line is 0-indexed
                !lines
                    .get(block.start_line)
                    .is_some_and(|l| l.in_kramdown_extension_block)
            })
            .collect::<Vec<_>>();
        let emphasis_spans = emphasis_spans
            .into_iter()
            .filter(|span| !lines.get(span.line - 1).is_some_and(|l| l.in_kramdown_extension_block))
            .collect::<Vec<_>>();

        // Mark lines covered by a list or table block so is_in_list_block /
        // is_in_table_block are O(1) reads (mirrors in_html_block) instead of
        // scanning the whole block vector on every call.
        for block in &list_blocks {
            // ListBlock line numbers are 1-indexed.
            for line_num in block.start_line..=block.end_line {
                if let Some(li) = lines.get_mut(line_num - 1) {
                    li.in_list_block = true;
                }
            }
        }
        for block in &table_blocks {
            // TableBlock line numbers are 0-indexed.
            for idx in block.start_line..=block.end_line {
                if let Some(li) = lines.get_mut(idx) {
                    li.in_table_block = true;
                }
            }
        }

        // Rebuild reference_defs_map after filtering
        let reference_defs_map: HashMap<String, usize> = reference_defs
            .iter()
            .enumerate()
            .map(|(idx, def)| (def.id.to_lowercase(), idx))
            .collect();

        // Pre-compute sorted link title byte ranges for binary search
        let link_title_ranges: Vec<(usize, usize)> = reference_defs
            .iter()
            .filter_map(|def| match (def.title_byte_start, def.title_byte_end) {
                (Some(start), Some(end)) => Some((start, end)),
                _ => None,
            })
            .collect();

        // Reuse already-computed line_offsets and code_blocks instead of re-detecting
        let line_index = profile_section!(
            "Line index",
            profile,
            crate::utils::range_utils::LineIndex::with_line_starts_and_code_blocks(
                content,
                line_offsets.clone(),
                &code_blocks,
            )
        );

        // Pre-compute Jinja template ranges once for all rules (eliminates O(n*m) in MD011)
        let jinja_ranges = profile_section!(
            "Jinja ranges",
            profile,
            crate::utils::jinja_utils::find_jinja_ranges(content)
        );

        // Pre-compute Pandoc/Quarto citation ranges for Pandoc-compatible flavors
        let citation_ranges = profile_section!("Citation ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::find_citation_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc inline footnote ranges for Pandoc-compatible flavors
        let inline_footnote_ranges = profile_section!("Inline footnote ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_inline_footnote_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc implicit header reference slugs for Pandoc-compatible flavors
        let pandoc_header_slugs = profile_section!("Pandoc header slugs", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::collect_pandoc_header_slugs(content)
            } else {
                std::collections::HashSet::new()
            }
        });

        // Pre-compute Pandoc example-list marker ranges for Pandoc-compatible flavors
        let example_list_marker_ranges = profile_section!("Example list markers", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_example_list_marker_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc example reference ranges for Pandoc-compatible flavors
        let example_reference_ranges = profile_section!("Example references", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_example_reference_ranges(content, &example_list_marker_ranges)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc subscript (~x~) and superscript (^x^) ranges
        let sub_super_ranges = profile_section!("Subscript/superscript ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_subscript_superscript_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc inline code attribute ranges (`code`{.lang}) for Pandoc-compatible flavors
        let inline_code_attr_ranges = profile_section!("Inline code attribute ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_inline_code_attr_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc bracketed span ranges ([text]{attrs}) for Pandoc-compatible flavors
        let bracketed_span_ranges = profile_section!("Bracketed span ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_bracketed_span_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc line block ranges (| text) for Pandoc-compatible flavors
        let line_block_ranges = profile_section!("Line block ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_line_block_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc pipe-table caption ranges (: caption) for Pandoc-compatible flavors
        let pipe_table_caption_ranges = profile_section!("Pipe-table caption ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_pipe_table_caption_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc YAML metadata block ranges (--- ... --- or ...) for Pandoc-compatible flavors
        let pandoc_metadata_ranges = profile_section!("Pandoc metadata ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_yaml_metadata_block_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc grid-table ranges (+---+---+) for Pandoc-compatible flavors
        let grid_table_ranges = profile_section!("Grid table ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_grid_table_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Pandoc multi-line table ranges for Pandoc-compatible flavors
        let multi_line_table_ranges = profile_section!("Multi-line table ranges", profile, {
            if flavor.is_pandoc_compatible() {
                crate::utils::pandoc::detect_multi_line_table_ranges(content)
            } else {
                Vec::new()
            }
        });

        // Pre-compute Hugo/Quarto shortcode ranges ({{< ... >}} and {{% ... %}})
        let shortcode_ranges = profile_section!("Shortcode ranges", profile, {
            use crate::utils::regex_cache::HUGO_SHORTCODE_REGEX;
            let mut ranges = Vec::new();
            for mat in HUGO_SHORTCODE_REGEX.find_iter(content) {
                ranges.push((mat.start(), mat.end()));
            }
            ranges
        });

        let inline_config =
            InlineConfig::from_content_with_code_blocks(content, &code_blocks, &code_span_byte_ranges(&code_spans));
        Self {
            content,
            content_lines,
            line_offsets,
            code_blocks,
            code_block_details,
            strong_spans,
            line_to_list,
            list_start_values,
            definition_lists,
            commonmark_ordered_lists_cache: OnceLock::new(),
            lines,
            blockquote_headings,
            links,
            images,
            broken_links,
            footnote_refs,
            reference_defs,
            reference_defs_map,
            code_spans_cache: OnceLock::from(Arc::new(code_spans)),
            math_spans_cache: OnceLock::new(), // Lazy-loaded on first access
            bracket_math_cache: OnceLock::new(),
            math_byte_ranges_cache: OnceLock::new(), // Lazy-loaded on first access
            list_blocks,
            char_frequency,
            html_tags_cache: OnceLock::new(),
            jsx_component_tags_cache: OnceLock::new(),
            emphasis_spans_cache: OnceLock::from(Arc::new(emphasis_spans)),
            bare_urls_cache: OnceLock::new(),
            has_mixed_list_nesting_cache: OnceLock::new(),
            html_comment_ranges,
            table_blocks,
            line_index,
            jinja_ranges,
            flavor,
            source_file,
            link_target_policy: None,
            invalid_utf8: None,
            jsx_expression_ranges,
            mdx_comment_ranges,
            citation_ranges,
            pandoc_div_ranges,
            colon_fence_details,
            inline_footnote_ranges,
            pandoc_header_slugs,
            example_list_marker_ranges,
            example_reference_ranges,
            sub_super_ranges,
            inline_code_attr_ranges,
            bracketed_span_ranges,
            line_block_ranges,
            pipe_table_caption_ranges,
            pandoc_metadata_ranges,
            grid_table_ranges,
            multi_line_table_ranges,
            shortcode_ranges,
            link_title_ranges,
            code_span_byte_ranges: code_span_ranges,
            inline_config,
            obsidian_comment_ranges,
            unterminated_html_comment,
            unterminated_obsidian_comment,
            lazy_cont_lines_cache: OnceLock::new(),
            myst_directive_ranges,
            myst_comment_ranges,
            myst_role_ranges,
            front_matter_end,
        }
    }

    /// The 1-indexed line number where front matter ends (the closing
    /// delimiter line), or 0 when the document has no front matter.
    /// Computed once in `new()`; rules must use this instead of re-scanning
    /// the content with `FrontMatterUtils`.
    pub fn front_matter_end_line(&self) -> usize {
        self.front_matter_end
    }

    /// Binary search for whether `pos` falls inside any range in a sorted, non-overlapping
    /// slice of `(start, end)` byte ranges. O(log n) instead of O(n).
    #[inline]
    fn binary_search_ranges(ranges: &[(usize, usize)], pos: usize) -> bool {
        // Find the rightmost range whose start <= pos
        let idx = ranges.partition_point(|&(start, _)| start <= pos);
        // If idx == 0, no range starts at or before pos
        idx > 0 && pos < ranges[idx - 1].1
    }

    /// Check if a byte position is within a code span. O(log n).
    pub fn is_in_code_span_byte(&self, pos: usize) -> bool {
        Self::binary_search_ranges(&self.code_span_byte_ranges, pos)
    }

    /// Whether the line ends with the backslash of a hard line break: the last
    /// of an odd run of backslashes written outside a code span. `line_number`
    /// is 1-indexed. A paragraph's last line ends with no break whatever it
    /// ends with; that is the caller's to know.
    pub fn line_ends_with_hard_break(&self, line_number: usize) -> bool {
        let line = &self.lines[line_number - 1];
        heading_detection::ends_with_hard_break(
            line.content(self.content),
            line.byte_offset,
            &self.code_span_byte_ranges,
        )
    }

    /// Check if `pos` is inside any link byte range. O(log n).
    pub fn is_in_link(&self, pos: usize) -> bool {
        self.link_containing(pos).is_some() || self.image_containing(pos).is_some() || self.is_in_reference_def(pos)
    }

    /// Check if `pos`` is within a bare URL
    pub fn is_in_bare_url(&self, pos: usize) -> bool {
        let bare_urls = self.bare_urls();
        // Binary search (sorted by byte_offset) for the candidate containing byte_pos
        let idx = bare_urls.partition_point(|url| url.byte_offset <= pos);
        idx > 0 && pos < bare_urls[idx - 1].byte_end
    }

    /// Get parsed inline configuration state.
    pub fn inline_config(&self) -> &InlineConfig {
        &self.inline_config
    }

    /// Azure DevOps colon code fences (`:::lang … :::`), each with its byte range
    /// and the opener's info string. These are detected outside the CommonMark
    /// parse, so they never appear in `code_block_details`. Empty for all other
    /// flavors.
    pub fn colon_fence_details(&self) -> &[CodeBlockDetail] {
        &self.colon_fence_details
    }

    /// Get pre-split content lines, avoiding repeated `content.lines().collect()` allocations.
    ///
    /// Lines are 0-indexed (line 0 corresponds to line number 1 in the document).
    pub fn raw_lines(&self) -> &[&'a str] {
        &self.content_lines
    }

    /// Check if a rule is disabled at a specific line number (1-indexed)
    ///
    /// This method checks both persistent disable comments (<!-- rumdl-disable -->)
    /// and line-specific comments (<!-- rumdl-disable-line -->, <!-- rumdl-disable-next-line -->).
    pub fn is_rule_disabled(&self, rule_name: &str, line_number: usize) -> bool {
        self.inline_config.is_rule_disabled(rule_name, line_number)
    }

    /// Get code spans - computed lazily on first access
    pub fn code_spans(&self) -> Arc<Vec<CodeSpan>> {
        Arc::clone(
            self.code_spans_cache
                .get_or_init(|| Arc::new(element_parsers::parse_code_spans(self.content, &self.lines))),
        )
    }

    /// Math byte ranges (`$...$` inline and `$$...$$` display), computed once and
    /// cached. Used by `is_in_math_context`; without the cache that helper
    /// rescanned the whole document on every call.
    pub fn math_byte_ranges(&self) -> &[(usize, usize)] {
        self.math_byte_ranges_cache
            .get_or_init(|| crate::utils::skip_context::math_byte_ranges(self.content))
    }

    /// Get math spans - computed lazily on first access
    pub fn math_spans(&self) -> Arc<Vec<MathSpan>> {
        Arc::clone(
            self.math_spans_cache
                .get_or_init(|| Arc::new(element_parsers::parse_math_spans(self.content, &self.lines))),
        )
    }

    /// Standalone TeX bracket display math, read only by MD013 when opted in.
    pub(crate) fn bracket_display_math_lines(&self) -> &bracket_math::BracketDisplayMathLines {
        self.bracket_math_cache
            .get_or_init(|| bracket_math::parse(self.content, &self.lines, &self.code_spans(), &self.list_blocks))
    }

    /// Check if a byte position is within a math span (inline $...$ or display $$...$$)
    pub fn is_in_math_span(&self, byte_pos: usize) -> bool {
        let math_spans = self.math_spans();
        // Binary search: find the last span whose byte_offset <= byte_pos
        let idx = math_spans.partition_point(|span| span.byte_offset <= byte_pos);
        idx > 0 && byte_pos < math_spans[idx - 1].byte_end
    }

    /// Get HTML comment ranges - pre-computed during LintContext construction
    pub fn html_comment_ranges(&self) -> &[crate::utils::skip_context::ByteRange] {
        &self.html_comment_ranges
    }

    /// Byte offset of a `<!--` that no `-->` closes, if the document has one.
    ///
    /// Everything after it is inside the comment as far as the parser is
    /// concerned, so no rule sees that text.
    pub fn unterminated_html_comment(&self) -> Option<usize> {
        self.unterminated_html_comment
    }

    /// Byte offset of a `%%` that no second `%%` closes, if the document has
    /// one. Always `None` outside the Obsidian flavor, where `%%` is ordinary
    /// text rather than a comment delimiter.
    pub fn unterminated_obsidian_comment(&self) -> Option<usize> {
        self.unterminated_obsidian_comment
    }

    /// Check if a byte position is inside an Obsidian comment
    ///
    /// Returns false for non-Obsidian flavors.
    pub fn is_in_obsidian_comment(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.obsidian_comment_ranges, byte_pos)
    }

    /// Check if a line/column position is inside an Obsidian comment
    ///
    /// Line number is 1-indexed, column is 1-indexed.
    /// Returns false for non-Obsidian flavors.
    pub fn is_position_in_obsidian_comment(&self, line_num: usize, col: usize) -> bool {
        if self.obsidian_comment_ranges.is_empty() {
            return false;
        }

        // Convert line/column (1-indexed, char-based) to byte position
        let byte_pos = self.line_index.line_col_to_byte_range(line_num, col).start;
        self.is_in_obsidian_comment(byte_pos)
    }

    /// Get byte ranges of MyST colon directive blocks
    pub fn myst_directive_ranges(&self) -> &[(usize, usize)] {
        &self.myst_directive_ranges
    }

    /// Check if a byte position is inside a MyST role (`{role}`content``)
    pub fn is_in_myst_role(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.myst_role_ranges, byte_pos)
    }

    /// Check if a byte position is inside a MyST comment (`% comment`)
    pub fn is_in_myst_comment(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.myst_comment_ranges, byte_pos)
    }

    /// Check if a line (1-indexed) is a MyST colon-fence directive opener (`:::{name} ...`).
    ///
    /// The text after `{name}` on an opener is the directive's argument (an opaque
    /// path, URL, or label), not markdown prose. Rules that reformat prose should
    /// skip these lines. Returns false for non-MyST flavors and for directive body
    /// or closer lines.
    pub fn is_myst_colon_directive_opener_line(&self, line_num: usize) -> bool {
        if !self.flavor.supports_myst_directives() {
            return false;
        }
        self.lines.get(line_num.wrapping_sub(1)).is_some_and(|info| {
            info.in_myst_directive
                && flavor_detection::myst_colon_directive_opener(info.content(self.content)).is_some()
        })
    }

    /// Drop tags that live inside kramdown extension blocks, preserving order.
    fn filter_kramdown_tags(&self, tags: Vec<HtmlTag>) -> Vec<HtmlTag> {
        tags.into_iter()
            .filter(|tag| {
                !self
                    .lines
                    .get(tag.line - 1)
                    .is_some_and(|l| l.in_kramdown_extension_block)
            })
            .collect()
    }

    /// Get HTML tags - computed lazily on first access.
    ///
    /// JSX component tags (e.g. `<Card .../>`) are excluded so HTML-specific rules
    /// keep ignoring them; use [`Self::jsx_component_tags`] to access those. The
    /// single underlying parse populates both caches at once.
    pub fn html_tags(&self) -> Arc<Vec<HtmlTag>> {
        Arc::clone(self.html_tags_cache.get_or_init(|| {
            let (html_tags, jsx_component_tags) =
                element_parsers::parse_html_tags(self.content, &self.lines, &self.code_blocks, self.flavor);
            // Populate the JSX-component cache from the same parse so it is built once.
            let _ = self
                .jsx_component_tags_cache
                .set(Arc::new(self.filter_kramdown_tags(jsx_component_tags)));
            Arc::new(self.filter_kramdown_tags(html_tags))
        }))
    }

    /// Get JSX component tags (e.g. `<Card .../>`) - computed lazily, sharing the
    /// HTML-tag parse. Always empty for flavors without JSX support.
    pub fn jsx_component_tags(&self) -> Arc<Vec<HtmlTag>> {
        if let Some(cached) = self.jsx_component_tags_cache.get() {
            return Arc::clone(cached);
        }
        // Trigger the shared parse, which also fills jsx_component_tags_cache.
        let _ = self.html_tags();
        Arc::clone(
            self.jsx_component_tags_cache
                .get()
                .expect("html_tags() populates jsx_component_tags_cache"),
        )
    }

    /// Get emphasis spans - pre-computed during construction
    pub fn emphasis_spans(&self) -> Arc<Vec<EmphasisSpan>> {
        Arc::clone(
            self.emphasis_spans_cache
                .get()
                .expect("emphasis_spans_cache initialized during construction"),
        )
    }

    /// Get bare URLs - computed lazily on first access
    pub fn bare_urls(&self) -> Arc<Vec<BareUrl>> {
        Arc::clone(self.bare_urls_cache.get_or_init(|| {
            Arc::new(element_parsers::parse_bare_urls(
                self.content,
                &self.lines,
                &self.code_blocks,
            ))
        }))
    }

    /// Get lazy continuation lines - computed lazily on first access
    pub fn lazy_continuation_lines(&self) -> Arc<Vec<LazyContLine>> {
        Arc::clone(self.lazy_cont_lines_cache.get_or_init(|| {
            Arc::new(element_parsers::detect_lazy_continuation_lines(
                self.content,
                &self.lines,
                &self.line_offsets,
            ))
        }))
    }

    /// Check if document has mixed ordered/unordered list nesting.
    /// Result is cached after first computation (document-level invariant).
    /// This is used by MD007 for smart style auto-detection.
    pub fn has_mixed_list_nesting(&self) -> bool {
        *self
            .has_mixed_list_nesting_cache
            .get_or_init(|| self.compute_mixed_list_nesting())
    }

    /// Internal computation for mixed list nesting (only called once per LintContext).
    fn compute_mixed_list_nesting(&self) -> bool {
        // Track parent list items by their marker position and type
        // Using marker_column instead of indent because it works correctly
        // for blockquoted content where indent doesn't account for the prefix
        // Stack stores: (marker_column, is_ordered)
        let mut stack: Vec<(usize, bool)> = Vec::new();
        let mut last_was_blank = false;

        for line_info in &self.lines {
            // Skip non-content lines (code blocks, frontmatter, HTML comments, etc.)
            if line_info.in_code_block
                || line_info.in_front_matter
                || line_info.in_mkdocstrings
                || line_info.in_html_comment
                || line_info.in_mdx_comment
                || line_info.in_esm_block
            {
                continue;
            }

            // OPTIMIZATION: Use pre-computed is_blank instead of content().trim()
            if line_info.is_blank {
                last_was_blank = true;
                continue;
            }

            if let Some(list_item) = &line_info.list_item {
                // Normalize column 1 to column 0 (consistent with MD007 check function)
                let current_pos = if list_item.marker_column == 1 {
                    0
                } else {
                    list_item.marker_column
                };

                // If there was a blank line and this item is at root level, reset stack
                if last_was_blank && current_pos == 0 {
                    stack.clear();
                }
                last_was_blank = false;

                // Pop items at same or greater position (they're siblings or deeper, not parents)
                while let Some(&(pos, _)) = stack.last() {
                    if pos >= current_pos {
                        stack.pop();
                    } else {
                        break;
                    }
                }

                // Check if immediate parent has different type - this is mixed nesting
                if let Some(&(_, parent_is_ordered)) = stack.last()
                    && parent_is_ordered != list_item.is_ordered
                {
                    return true; // Found mixed nesting - early exit
                }

                stack.push((current_pos, list_item.is_ordered));
            } else {
                // Non-list line (but not blank) - could be paragraph or other content
                last_was_blank = false;
            }
        }

        false
    }

    /// Map a byte offset to (line, column).
    ///
    /// The column is a 1-indexed *character* offset within the line (rumdl's
    /// diagnostic convention), not a byte offset, so it is correct on lines
    /// containing multi-byte UTF-8 characters.
    pub fn offset_to_line_col(&self, offset: usize) -> (usize, usize) {
        match self.line_offsets.binary_search(&offset) {
            Ok(line) => (line + 1, 1),
            Err(line) => {
                let line_start = self.line_offsets.get(line.wrapping_sub(1)).copied().unwrap_or(0);
                // Convert the byte offset within the line to a character column.
                let col = byte_to_char_count(&self.content[line_start..], offset.saturating_sub(line_start));
                (line, col)
            }
        }
    }

    /// Return the byte offset at which a 1-indexed source line starts.
    ///
    /// This is the inverse-facing half of [`Self::offset_to_line_col`]. Keeping
    /// both conversions on the document prevents rules from depending on the
    /// line-index representation or reconstructing it independently.
    pub fn line_start_byte(&self, line_number: usize) -> Option<usize> {
        self.line_index.get_line_start_byte(line_number)
    }

    /// Return an empty byte range at a 1-indexed line and character column.
    ///
    /// Columns are character offsets, not UTF-8 byte offsets. Positions past
    /// the end of a line clamp to the end of its content; missing lines clamp to
    /// the end of the document.
    pub fn line_column_byte_range(&self, line_number: usize, column: usize) -> Range<usize> {
        self.line_index.line_col_to_byte_range(line_number, column)
    }

    /// Return a byte range beginning at a 1-indexed line and character column.
    ///
    /// `length` is measured in characters. The result never crosses the line's
    /// content boundary and excludes its line ending.
    pub fn line_column_byte_range_with_length(&self, line_number: usize, column: usize, length: usize) -> Range<usize> {
        self.line_index
            .line_col_to_byte_range_with_length(line_number, column, length)
    }

    /// Return the byte range of a complete 1-indexed line, including its line
    /// ending when one is present.
    pub fn whole_line_byte_range(&self, line_number: usize) -> Range<usize> {
        self.line_index.whole_line_range(line_number)
    }

    /// Return the byte range between two 1-indexed character columns on a line.
    ///
    /// The range excludes the line ending and clamps both columns to valid
    /// character boundaries in the line content.
    pub fn line_text_byte_range(&self, line_number: usize, start_column: usize, end_column: usize) -> Range<usize> {
        self.line_index.line_text_range(line_number, start_column, end_column)
    }

    /// Return the byte range of a 1-indexed line's content, excluding its line
    /// ending.
    pub fn line_content_byte_range(&self, line_number: usize) -> Range<usize> {
        self.line_index.line_content_range(line_number)
    }

    /// Return the byte range spanning complete 1-indexed lines, inclusive.
    pub fn line_span_byte_range(&self, start_line: usize, end_line: usize) -> Range<usize> {
        self.line_index.multi_line_range(start_line, end_line)
    }

    /// Check if a position is within a code block or code span. O(log n).
    pub fn is_in_code_block_or_span(&self, pos: usize) -> bool {
        // Check code blocks first (already uses binary search internally)
        if CodeBlockUtils::is_in_code_block_or_span(&self.code_blocks, pos) {
            return true;
        }

        // Check inline code spans via binary search
        self.is_byte_offset_in_code_span(pos)
    }

    /// Get line information by line number (1-indexed)
    pub fn line_info(&self, line_num: usize) -> Option<&LineInfo> {
        if line_num > 0 {
            self.lines.get(line_num - 1)
        } else {
            None
        }
    }

    /// Parsed links in document order.
    pub fn links(&self) -> &[ParsedLink<'a>] {
        &self.links
    }

    /// Parsed images in document order.
    pub fn images(&self) -> &[ParsedImage<'a>] {
        &self.images
    }

    /// Broken or undefined reference links in document order.
    pub fn broken_links(&self) -> &[BrokenLinkInfo] {
        &self.broken_links
    }

    /// Parsed footnote references in document order.
    pub fn footnote_references(&self) -> &[FootnoteRef] {
        &self.footnote_refs
    }

    /// Parsed reference definitions in document order.
    pub fn reference_definitions(&self) -> &[ReferenceDef] {
        &self.reference_defs
    }

    /// Links whose opening delimiter starts on `line_number` (1-indexed).
    pub fn links_on_line(&self, line_number: usize) -> &[ParsedLink<'a>] {
        let start = self.links.partition_point(|link| link.line < line_number);
        let end = self.links.partition_point(|link| link.line <= line_number);
        &self.links[start..end]
    }

    /// Images whose opening delimiter starts on `line_number` (1-indexed).
    pub fn images_on_line(&self, line_number: usize) -> &[ParsedImage<'a>] {
        let start = self.images.partition_point(|image| image.line < line_number);
        let end = self.images.partition_point(|image| image.line <= line_number);
        &self.images[start..end]
    }

    /// Find the link that starts at an exact byte offset. O(log n).
    pub fn link_starting_at(&self, byte_offset: usize) -> Option<&ParsedLink<'a>> {
        self.links
            .binary_search_by_key(&byte_offset, |link| link.byte_offset)
            .ok()
            .map(|index| &self.links[index])
    }

    /// Find the image that starts at an exact byte offset. O(log n).
    pub fn image_starting_at(&self, byte_offset: usize) -> Option<&ParsedImage<'a>> {
        self.images
            .binary_search_by_key(&byte_offset, |image| image.byte_offset)
            .ok()
            .map(|index| &self.images[index])
    }

    /// Find the parsed link containing `byte_offset`. O(log n).
    pub fn link_containing(&self, byte_offset: usize) -> Option<&ParsedLink<'a>> {
        let index = self.links.partition_point(|link| link.byte_offset <= byte_offset);
        self.links
            .get(index.checked_sub(1)?)
            .filter(|link| byte_offset < link.byte_end)
    }

    /// Find the parsed image containing `byte_offset`. O(log n).
    pub fn image_containing(&self, byte_offset: usize) -> Option<&ParsedImage<'a>> {
        let index = self.images.partition_point(|image| image.byte_offset <= byte_offset);
        self.images
            .get(index.checked_sub(1)?)
            .filter(|image| byte_offset < image.byte_end)
    }

    /// Links that start at or before `byte_offset`, in document order. O(log n).
    pub fn links_starting_before_or_at(&self, byte_offset: usize) -> &[ParsedLink<'a>] {
        let end = self.links.partition_point(|link| link.byte_offset <= byte_offset);
        &self.links[..end]
    }

    /// Find a reference definition by its case-insensitive identifier.
    pub fn reference_definition(&self, ref_id: &str) -> Option<&ReferenceDef> {
        let normalized_id = ref_id.to_lowercase();
        self.reference_defs_map
            .get(&normalized_id)
            .map(|&index| &self.reference_defs[index])
    }

    /// Get URL for a reference link/image by its ID (O(1) lookup via HashMap)
    pub fn get_reference_url(&self, ref_id: &str) -> Option<&str> {
        self.reference_definition(ref_id)
            .map(|definition| definition.url.as_str())
    }

    /// Check if a line is part of a list block
    pub fn is_in_list_block(&self, line_num: usize) -> bool {
        if line_num == 0 || line_num > self.lines.len() {
            return false;
        }
        self.lines[line_num - 1].in_list_block
    }

    /// Check if a line is inside a definition list, as the parser reads it
    ///
    /// Terms count, and so does everything nested in a definition, but the blank
    /// lines between items do not. A colon touching its text (`:warning:`) opens
    /// no definition here, though pulldown-cmark reads one, so its term is free
    /// text even between two items that do count. This is the parser's answer for every flavor,
    /// unlike `LineInfo::in_definition_list`, which only MkDocs populates.
    pub fn is_in_definition_list(&self, line_num: usize) -> bool {
        let lists = &self.definition_lists.outer;
        let idx = lists.partition_point(|&(start, _)| start <= line_num);
        idx > 0 && line_num <= lists[idx - 1].1
    }

    /// Check if a line is part of a definition list term
    pub fn is_definition_term(&self, line_num: usize) -> bool {
        let terms = &self.definition_lists.terms;
        let idx = terms.partition_point(|&(_, end)| end < line_num);
        terms.get(idx).is_some_and(|&(start, _)| start <= line_num)
    }

    /// The definition text containing a line, if any
    pub fn definition_text_at(&self, line_num: usize) -> Option<&DefinitionText> {
        let texts = &self.definition_lists.texts;
        let idx = texts.partition_point(|text| text.end_line < line_num);
        texts.get(idx).filter(|text| text.start_line <= line_num)
    }

    /// Check if a line is within an HTML block
    pub fn is_in_html_block(&self, line_num: usize) -> bool {
        if line_num == 0 || line_num > self.lines.len() {
            return false;
        }
        self.lines[line_num - 1].in_html_block
    }

    /// Check if a 1-indexed line number is inside a GFM table block.
    ///
    /// Returns `true` for the header line, delimiter line, and all body rows.
    /// `TableBlock` spans are stored 0-indexed; this helper accepts the
    /// 1-indexed line numbers used elsewhere in the rule API.
    pub fn is_in_table_block(&self, line_num: usize) -> bool {
        if line_num == 0 || line_num > self.lines.len() {
            return false;
        }
        self.lines[line_num - 1].in_table_block
    }

    /// Check if a line and column is within a code span
    pub fn is_in_code_span(&self, line_num: usize, col: usize) -> bool {
        if line_num == 0 || line_num > self.lines.len() {
            return false;
        }

        // Use the code spans cache to check
        // Note: col is 1-indexed from caller, but span.start_col and span.end_col are 0-indexed
        // Convert col to 0-indexed for comparison
        let col_0indexed = if col > 0 { col - 1 } else { 0 };
        let code_spans = self.code_spans();
        code_spans.iter().any(|span| {
            // Check if line is within the span's line range
            if line_num < span.line || line_num > span.end_line {
                return false;
            }

            if span.line == span.end_line {
                // Single-line span: check column bounds
                col_0indexed >= span.start_col && col_0indexed < span.end_col
            } else if line_num == span.line {
                // First line of multi-line span: anything after start_col is in span
                col_0indexed >= span.start_col
            } else if line_num == span.end_line {
                // Last line of multi-line span: anything before end_col is in span
                col_0indexed < span.end_col
            } else {
                // Middle line of multi-line span: entire line is in span
                true
            }
        })
    }

    /// Check if a byte offset is within a code span. O(log n).
    #[inline]
    pub fn is_byte_offset_in_code_span(&self, byte_offset: usize) -> bool {
        let code_spans = self.code_spans();
        let idx = code_spans.partition_point(|span| span.byte_offset <= byte_offset);
        idx > 0 && byte_offset < code_spans[idx - 1].byte_end
    }

    /// Check if a byte position is within a reference definition. O(log n).
    #[inline]
    pub fn is_in_reference_def(&self, byte_pos: usize) -> bool {
        let idx = self.reference_defs.partition_point(|rd| rd.byte_offset <= byte_pos);
        idx > 0 && byte_pos < self.reference_defs[idx - 1].byte_end
    }

    /// Check if a byte position is within an HTML comment. O(log n).
    #[inline]
    pub fn is_in_html_comment(&self, byte_pos: usize) -> bool {
        let idx = self.html_comment_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.html_comment_ranges[idx - 1].end
    }

    /// Check if a byte position is within an HTML tag (including multiline tags).
    /// Uses the pre-parsed html_tags which correctly handles tags spanning multiple lines. O(log n).
    #[inline]
    pub fn is_in_html_tag(&self, byte_pos: usize) -> bool {
        let tags = self.html_tags();
        let idx = tags.partition_point(|tag| tag.byte_offset <= byte_pos);
        idx > 0 && byte_pos < tags[idx - 1].byte_end
    }

    /// Check if a byte position is within a JSX component tag (e.g. `<Card .../>`),
    /// including its attribute values and multiline tags. Always false for flavors
    /// without JSX support. O(log n).
    #[inline]
    pub fn is_in_jsx_component_tag(&self, byte_pos: usize) -> bool {
        if !self.flavor.supports_jsx() {
            return false;
        }
        let tags = self.jsx_component_tags();
        let idx = tags.partition_point(|tag| tag.byte_offset <= byte_pos);
        idx > 0 && byte_pos < tags[idx - 1].byte_end
    }

    /// Check if a byte position is within a Jinja template ({{ }} or {% %}). O(log n).
    pub fn is_in_jinja_range(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.jinja_ranges, byte_pos)
    }

    /// Check if a byte position is within a JSX expression (MDX: {expression}). O(log n).
    #[inline]
    pub fn is_in_jsx_expression(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.jsx_expression_ranges, byte_pos)
    }

    /// Check if a byte position is within an MDX comment ({/* ... */}). O(log n).
    #[inline]
    pub fn is_in_mdx_comment(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.mdx_comment_ranges, byte_pos)
    }

    /// Check if a byte position is within a Pandoc/Quarto citation (`@key` or `[@key]`).
    /// Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_citation(&self, byte_pos: usize) -> bool {
        let idx = self.citation_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.citation_ranges[idx - 1].end
    }

    /// Pre-computed Pandoc/Quarto citation ranges.
    #[inline]
    pub fn citation_ranges(&self) -> &[crate::utils::skip_context::ByteRange] {
        &self.citation_ranges
    }

    /// Check if a byte position is within a Pandoc/Quarto div block (`::: ... :::`).
    /// Active for Pandoc-compatible flavors. O(log n) via binary search over sorted ranges.
    #[inline]
    pub fn is_in_div_block(&self, byte_pos: usize) -> bool {
        let idx = self.pandoc_div_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.pandoc_div_ranges[idx - 1].end
    }

    /// Check if a byte position is within a Pandoc inline footnote (`^[note text]`).
    /// Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_inline_footnote(&self, byte_pos: usize) -> bool {
        let idx = self.inline_footnote_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.inline_footnote_ranges[idx - 1].end
    }

    /// Check if a byte position is within a Pandoc example-list marker (`(@)` /
    /// `(@label)` at line start). Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_example_list_marker(&self, byte_pos: usize) -> bool {
        let idx = self.example_list_marker_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.example_list_marker_ranges[idx - 1].end
    }

    /// Check if a byte position is within a Pandoc example reference (`(@label)`
    /// inline). Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_example_reference(&self, byte_pos: usize) -> bool {
        let idx = self.example_reference_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.example_reference_ranges[idx - 1].end
    }

    /// Check if a byte position is within a Pandoc subscript (`~x~`) or
    /// superscript (`^x^`) span. Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_subscript_or_superscript(&self, byte_pos: usize) -> bool {
        let idx = self.sub_super_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.sub_super_ranges[idx - 1].end
    }

    /// Check if a byte position is within a Pandoc inline-code attribute block
    /// (`{.lang}` immediately following `` `code` ``). Active for Pandoc-compatible
    /// flavors. O(log n).
    #[inline]
    pub fn is_in_inline_code_attr(&self, byte_pos: usize) -> bool {
        let idx = self.inline_code_attr_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.inline_code_attr_ranges[idx - 1].end
    }

    /// Check if a byte position is within a Pandoc bracketed span (`[text]{attrs}`).
    /// Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_bracketed_span(&self, byte_pos: usize) -> bool {
        let idx = self.bracketed_span_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.bracketed_span_ranges[idx - 1].end
    }

    /// Returns true if `byte_pos` falls inside a Pandoc line block (`| text`).
    /// Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_line_block(&self, byte_pos: usize) -> bool {
        let idx = self.line_block_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.line_block_ranges[idx - 1].end
    }

    /// Returns true if `byte_pos` falls inside a Pandoc pipe-table caption
    /// (`: caption` adjacent to a pipe table). Active for Pandoc-compatible
    /// flavors. O(log n).
    #[inline]
    pub fn is_in_pipe_table_caption(&self, byte_pos: usize) -> bool {
        let idx = self.pipe_table_caption_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.pipe_table_caption_ranges[idx - 1].end
    }

    /// Returns true if `byte_pos` falls inside a Pandoc YAML metadata block.
    /// Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_pandoc_metadata(&self, byte_pos: usize) -> bool {
        let idx = self.pandoc_metadata_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.pandoc_metadata_ranges[idx - 1].end
    }

    /// Returns true if `byte_pos` falls inside a Pandoc grid table.
    /// Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_grid_table(&self, byte_pos: usize) -> bool {
        let idx = self.grid_table_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.grid_table_ranges[idx - 1].end
    }

    /// Returns true if `byte_pos` falls inside a Pandoc multi-line table.
    /// Active for Pandoc-compatible flavors. O(log n).
    #[inline]
    pub fn is_in_multi_line_table(&self, byte_pos: usize) -> bool {
        let idx = self.multi_line_table_ranges.partition_point(|r| r.start <= byte_pos);
        idx > 0 && byte_pos < self.multi_line_table_ranges[idx - 1].end
    }

    /// Returns true if `link_text`, after Pandoc slugification, matches a heading
    /// in the document. Returns false for non-Pandoc-compatible flavors because
    /// the `pandoc_header_slugs` set is empty when the pre-pass detector is gated
    /// off. Use this when the caller has raw bracketed text (`[Section name]`).
    pub fn matches_implicit_header_reference(&self, link_text: &str) -> bool {
        let slug = crate::utils::pandoc::pandoc_header_slug(link_text);
        self.pandoc_header_slugs.contains(&slug)
    }

    /// Returns true if `slug` (already in Pandoc-slug form) matches a heading
    /// in the document. Returns false for non-Pandoc-compatible flavors because
    /// the `pandoc_header_slugs` set is empty when the pre-pass detector is gated
    /// off. Use this when the caller already has a slug (e.g. the fragment of a
    /// URL after `#`). O(1).
    #[inline]
    pub fn has_pandoc_slug(&self, slug: &str) -> bool {
        self.pandoc_header_slugs.contains(slug)
    }

    /// Check if a byte position is within a Hugo/Quarto shortcode ({{< ... >}} or {{% ... %}}). O(log n).
    #[inline]
    pub fn is_in_shortcode(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.shortcode_ranges, byte_pos)
    }

    /// Pre-computed Hugo/Quarto shortcode ranges.
    #[inline]
    pub fn shortcode_ranges(&self) -> &[(usize, usize)] {
        &self.shortcode_ranges
    }

    /// Check if a byte position is within a link reference definition title. O(log n).
    pub fn is_in_link_title(&self, byte_pos: usize) -> bool {
        Self::binary_search_ranges(&self.link_title_ranges, byte_pos)
    }

    /// Check if content has any instances of a specific character (fast)
    pub fn has_char(&self, ch: char) -> bool {
        match ch {
            '#' => self.char_frequency.hash_count > 0,
            '*' => self.char_frequency.asterisk_count > 0,
            '_' => self.char_frequency.underscore_count > 0,
            '-' => self.char_frequency.hyphen_count > 0,
            '+' => self.char_frequency.plus_count > 0,
            '>' => self.char_frequency.gt_count > 0,
            '|' => self.char_frequency.pipe_count > 0,
            '[' => self.char_frequency.bracket_count > 0,
            '`' => self.char_frequency.backtick_count > 0,
            '<' => self.char_frequency.lt_count > 0,
            '!' => self.char_frequency.exclamation_count > 0,
            '\n' => self.char_frequency.newline_count > 0,
            _ => self.content.contains(ch), // Fallback for other characters
        }
    }

    /// Get count of a specific character (fast)
    pub fn char_count(&self, ch: char) -> usize {
        match ch {
            '#' => self.char_frequency.hash_count,
            '*' => self.char_frequency.asterisk_count,
            '_' => self.char_frequency.underscore_count,
            '-' => self.char_frequency.hyphen_count,
            '+' => self.char_frequency.plus_count,
            '>' => self.char_frequency.gt_count,
            '|' => self.char_frequency.pipe_count,
            '[' => self.char_frequency.bracket_count,
            '`' => self.char_frequency.backtick_count,
            '<' => self.char_frequency.lt_count,
            '!' => self.char_frequency.exclamation_count,
            '\n' => self.char_frequency.newline_count,
            _ => self.content.matches(ch).count(), // Fallback for other characters
        }
    }

    /// Check if content likely contains headings (fast). A setext underline can
    /// be a single `-` or `=`, so one of either may make a heading.
    pub fn likely_has_headings(&self) -> bool {
        self.char_frequency.hash_count > 0 || self.char_frequency.hyphen_count > 0 || self.content.contains('=')
    }

    /// Check if content likely contains unordered lists (fast). Only bullet
    /// characters are counted, so an ordered-only document answers false;
    /// rules about ordered lists read `commonmark_ordered_lists` instead.
    pub fn likely_has_lists(&self) -> bool {
        self.char_frequency.asterisk_count > 0
            || self.char_frequency.hyphen_count > 0
            || self.char_frequency.plus_count > 0
    }

    /// Check if content likely contains emphasis (fast)
    pub fn likely_has_emphasis(&self) -> bool {
        self.char_frequency.asterisk_count > 1 || self.char_frequency.underscore_count > 1
    }

    /// Check if content likely contains tables (fast)
    pub fn likely_has_tables(&self) -> bool {
        self.char_frequency.pipe_count > 2
    }

    /// Check if content likely contains blockquotes (fast)
    pub fn likely_has_blockquotes(&self) -> bool {
        self.char_frequency.gt_count > 0
    }

    /// Check if content likely contains code (fast)
    pub fn likely_has_code(&self) -> bool {
        self.char_frequency.backtick_count > 0
    }

    /// Check if content likely contains links or images (fast)
    pub fn likely_has_links_or_images(&self) -> bool {
        self.char_frequency.bracket_count > 0 || self.char_frequency.exclamation_count > 0
    }

    /// Check if content likely contains HTML (fast)
    pub fn likely_has_html(&self) -> bool {
        self.char_frequency.lt_count > 0
    }

    /// Get the blockquote prefix for inserting a blank line at the given line index.
    /// Returns the prefix without trailing content (e.g., ">" or ">>").
    /// This is needed because blank lines inside blockquotes must preserve the blockquote structure.
    /// Returns an empty string if the line is not inside a blockquote.
    pub fn blockquote_prefix_for_blank_line(&self, line_idx: usize) -> String {
        if let Some(line_info) = self.lines.get(line_idx)
            && let Some(ref bq) = line_info.blockquote
        {
            bq.prefix.trim_end().to_string()
        } else {
            String::new()
        }
    }

    /// Find the line index for a given byte offset using binary search.
    /// Returns (line_index, line_number, column) where:
    /// - line_index is the 0-based index in the lines array
    /// - line_number is the 1-based line number
    /// - column is the 0-based *character* offset within that line
    ///
    /// The column is a character offset rather than a byte offset so that the
    /// `start_col`/`end_col` it feeds into match rumdl's diagnostic convention
    /// (columns are character positions). On lines with multi-byte UTF-8
    /// characters the two differ; reporting bytes would mis-position highlights.
    #[inline]
    fn find_line_for_offset(lines: &[LineInfo], content: &str, byte_offset: usize) -> (usize, usize, usize) {
        // Binary search to find the line containing this byte offset
        let idx = match lines.binary_search_by(|line| {
            if byte_offset < line.byte_offset {
                std::cmp::Ordering::Greater
            } else if byte_offset > line.byte_offset + line.byte_len {
                std::cmp::Ordering::Less
            } else {
                std::cmp::Ordering::Equal
            }
        }) {
            Ok(idx) => idx,
            Err(idx) => idx.saturating_sub(1),
        };

        let line = &lines[idx];
        let line_num = idx + 1;
        let byte_col = byte_offset.saturating_sub(line.byte_offset);
        // Convert the byte offset within the line to a 0-based character column.
        // `byte_to_char_count` returns a 1-based value, so subtract 1.
        let col = byte_to_char_count(line.content(content), byte_col) - 1;

        (idx, line_num, col)
    }

    /// Check if a byte offset is within a code span using binary search
    #[inline]
    fn is_offset_in_code_span(code_spans: &[CodeSpan], offset: usize) -> bool {
        // Since spans are sorted by byte_offset, use partition_point for binary search
        let idx = code_spans.partition_point(|span| span.byte_offset <= offset);

        // Check the span that starts at or before our offset
        if idx > 0 {
            let span = &code_spans[idx - 1];
            if offset >= span.byte_offset && offset < span.byte_end {
                return true;
            }
        }

        false
    }

    /// Get an iterator over valid headings (skipping invalid ones like `#NoSpace`)
    ///
    /// Valid headings have proper spacing after the `#` markers (or are level > 1).
    /// This is the standard iterator for rules that need to process headings.
    ///
    /// # Examples
    ///
    /// ```
    /// use rumdl_lib::lint_context::LintContext;
    /// use rumdl_lib::config::MarkdownFlavor;
    ///
    /// let content = "# Valid Heading\n#NoSpace\n## Another Valid";
    /// let ctx = LintContext::new(content, MarkdownFlavor::Standard, None);
    ///
    /// for heading in ctx.valid_headings() {
    ///     println!("Line {}: {} (level {})", heading.line_num, heading.heading.text, heading.heading.level);
    /// }
    /// // Only prints valid headings, skips `#NoSpace`
    /// ```
    #[must_use]
    pub fn valid_headings(&self) -> ValidHeadingsIter<'_> {
        ValidHeadingsIter::new(&self.lines)
    }

    /// Check if the document contains any CommonMark headings
    ///
    /// A line like `#NoSpace` is paragraph text and does not count.
    #[must_use]
    pub fn has_valid_headings(&self) -> bool {
        self.lines.iter().any(|line| line.heading.is_some())
    }

    /// Iterate over every parsed list item in source order.
    #[must_use]
    pub fn list_items(&self) -> ParsedListItemsIter<'_> {
        ParsedListItemsIter::new(&self.lines)
    }

    /// Return the parsed list item on a 1-indexed source line, if any.
    #[must_use]
    pub fn list_item_on_line(&self, line_num: usize) -> Option<ParsedListItem<'_>> {
        let line_info = self.lines.get(line_num.checked_sub(1)?)?;
        Some(ParsedListItem::new(
            line_num,
            line_info.list_item.as_deref()?,
            line_info,
        ))
    }

    /// Borrow the document's parsed list blocks and their item iterators.
    #[must_use]
    pub fn parsed_list_blocks(&self) -> ParsedListBlocks<'_> {
        ParsedListBlocks::new(&self.list_blocks, &self.lines)
    }

    /// The item lines of `block` grouped into the lists they form, one group
    /// per list as CommonMark nests them, in source order, so siblings can be
    /// compared without the nested items that sit between them.
    #[must_use]
    pub fn list_block_item_groups(&self, block: &ListBlock) -> Vec<Vec<usize>> {
        list_blocks::item_lines_by_list(self.content, &self.lines, block)
    }

    /// Whether the document contains any parsed list items.
    #[must_use]
    pub fn has_list_items(&self) -> bool {
        self.lines.iter().any(|line| line.list_item.is_some())
    }

    /// Whether the document contains any parsed unordered-list items.
    #[must_use]
    pub fn has_unordered_list_items(&self) -> bool {
        self.lines
            .iter()
            .any(|line| line.list_item.as_ref().is_some_and(|item| !item.is_ordered))
    }

    /// Borrow ordered lists using the membership and start values determined by CommonMark.
    #[must_use]
    pub fn commonmark_ordered_lists(&self) -> CommonMarkOrderedLists<'_> {
        let lists = self
            .commonmark_ordered_lists_cache
            .get_or_init(|| build_commonmark_ordered_lists(&self.lines, &self.line_to_list, &self.list_start_values));
        CommonMarkOrderedLists::new(lists, &self.lines)
    }

    /// Iterate over every heading recognized in the rendered document.
    ///
    /// This includes top-level ATX and Setext headings, ATX headings nested in
    /// blockquotes, and malformed top-level ATX headings retained for
    /// diagnostics. Code blocks, front matter, raw HTML blocks, and
    /// flavor-specific non-Markdown regions are excluded during parsing;
    /// explicitly Markdown-enabled HTML containers remain eligible.
    #[must_use]
    pub fn headings(&self) -> ParsedHeadingsIter<'_> {
        ParsedHeadingsIter::new(&self.lines, &self.blockquote_headings)
    }

    /// Return the parsed heading on a 1-indexed source line, if any.
    #[must_use]
    pub fn heading_on_line(&self, line_num: usize) -> Option<ParsedHeading<'_>> {
        let idx = line_num.checked_sub(1)?;
        let line_info = self.lines.get(idx)?;
        let (heading, blockquote_depth) = match line_info.heading.as_deref() {
            Some(heading) => (heading, 0),
            None => (
                self.blockquote_headings.get(idx)?.as_deref()?,
                line_info.blockquote.as_ref().map_or(0, |bq| bq.nesting_level),
            ),
        };
        Some(ParsedHeading {
            line_num,
            heading,
            line_info,
            text_line_infos: &self.lines[idx + 1 - heading.text_lines..=idx],
            blockquote_depth,
        })
    }
}

/// The range an unclosed `<!--` hides when it opens a block the parser missed.
///
/// A MkDocs admonition or a `<div markdown>` body is rendered as markdown in its
/// own right, so a `<!--` starting one of its lines opens an HTML block there
/// just as it would at the top level. The parser has no notion of either
/// container, reads the body as indented code or as a lazy paragraph
/// continuation, and so reports no block for the opener to run to the end of.
///
/// The block ends where the container's body ends, which is what CommonMark
/// gives an unclosed comment in any other container. An opener that is not the
/// first thing on its line is inline HTML and opens nothing, here as anywhere.
fn container_comment_range(
    opener: usize,
    containers: &flavor_detection::ContainerLines,
    lines: &[types::LineInfo],
    content: &str,
) -> Option<crate::utils::skip_context::ByteRange> {
    let line_index = lines
        .partition_point(|line| line.byte_offset <= opener)
        .checked_sub(1)?;
    let line = lines.get(line_index)?;
    if line.byte_offset + line.indent != opener {
        return None;
    }
    if !containers.is_container_body(line_index) {
        return None;
    }
    let end_line = lines.get(containers.body_end_line(line_index)?)?;
    Some(crate::utils::skip_context::ByteRange {
        start: opener,
        end: (end_line.byte_offset + end_line.byte_len).min(content.len()),
    })
}

/// Parser-detected definition lists, converted from byte ranges to lines
#[derive(Debug)]
struct DefinitionListLines {
    /// Items of outermost lists as inclusive 1-indexed line ranges, sorted and
    /// disjoint, nested items merged into the item holding them
    outer: Vec<(usize, usize)>,
    /// Terms as inclusive 1-indexed line ranges, sorted and disjoint
    terms: Vec<(usize, usize)>,
    /// Definition texts, sorted and disjoint
    texts: Vec<DefinitionText>,
}

impl DefinitionListLines {
    fn new(
        line_offsets: &[usize],
        items: &[(usize, usize)],
        terms: &[(usize, usize)],
        texts: &[crate::utils::code_block_utils::DefinitionTextDetail],
    ) -> Self {
        // A range's end is exclusive and can sit just past the newline ending
        // its last line, so the last line is the one holding the byte before it.
        let line_of = |byte: usize| line_offsets.partition_point(|&offset| offset <= byte).max(1);
        let last_line_of = |start: usize, end: usize| line_of(end.saturating_sub(1).max(start));

        // Items arrive in document order, a nested item after the item holding
        // it, so each merges into the last range when it starts inside it.
        let mut outer: Vec<(usize, usize)> = Vec::new();
        for &(start, end) in items {
            let (start_line, end_line) = (line_of(start), last_line_of(start, end));
            match outer.last_mut() {
                Some(last) if start_line <= last.1 => last.1 = last.1.max(end_line),
                _ => outer.push((start_line, end_line)),
            }
        }
        let terms = terms
            .iter()
            .map(|&(start, end)| (line_of(start), last_line_of(start, end)))
            .collect();

        let texts = texts
            .iter()
            .map(|text| {
                let start_line = line_of(text.start);
                let line_start = line_offsets[start_line - 1];
                let on_marker_line = line_of(text.definition_start) == start_line;
                DefinitionText {
                    start_line,
                    end_line: last_line_of(text.start, text.end),
                    marker_prefix_len: on_marker_line.then(|| text.start - line_start),
                }
            })
            .collect();

        Self { outer, terms, texts }
    }
}

/// Detect footnote definitions and mark their continuation lines.
///
/// Uses pulldown-cmark to find footnote definition ranges and fenced code
/// blocks within them, then:
/// 1. Sets `in_footnote_definition = true` on all lines within
/// 2. Clears `in_code_block = false` on continuation lines that were
///    misidentified as indented code blocks (but preserves real fenced
///    code blocks within footnotes)
fn detect_footnote_definitions(content: &str, lines: &mut [types::LineInfo], line_offsets: &[usize]) {
    use pulldown_cmark::{CodeBlockKind, Event, Parser, Tag, TagEnd};

    let options = crate::utils::rumdl_parser_options();
    let parser = Parser::new_ext(content, options).into_offset_iter();

    // Collect footnote ranges and fenced code block ranges within them
    let mut footnote_ranges: Vec<(usize, usize)> = Vec::new();
    let mut fenced_code_ranges: Vec<(usize, usize)> = Vec::new();
    let mut in_footnote = false;

    for (event, range) in parser {
        match event {
            Event::Start(Tag::FootnoteDefinition(_)) => {
                in_footnote = true;
                footnote_ranges.push((range.start, range.end));
            }
            Event::End(TagEnd::FootnoteDefinition) => {
                in_footnote = false;
            }
            Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(_))) if in_footnote => {
                fenced_code_ranges.push((range.start, range.end));
            }
            _ => {}
        }
    }

    let byte_to_line = |byte_offset: usize| -> usize {
        line_offsets
            .partition_point(|&offset| offset <= byte_offset)
            .saturating_sub(1)
    };

    // Mark footnote definition lines
    for &(start, end) in &footnote_ranges {
        let start_line = byte_to_line(start);
        let end_line = line_offsets.partition_point(|&offset| offset < end).min(lines.len());

        for line in &mut lines[start_line..end_line] {
            line.in_footnote_definition = true;
            line.in_code_block = false;
        }
    }

    // Restore in_code_block for fenced code blocks within footnotes
    for &(start, end) in &fenced_code_ranges {
        let start_line = byte_to_line(start);
        let end_line = line_offsets.partition_point(|&offset| offset < end).min(lines.len());

        for line in &mut lines[start_line..end_line] {
            line.in_code_block = true;
        }
    }
}