brief/

convert.rs

//! Markdown-to-Brief converter.
//!
//! Walks a `pulldown-cmark` event stream and emits Brief source text. Every
//! Markdown construct that has no clean Brief equivalent is reported as a
//! `Diag` carrying a `Hole` code; nothing is silently dropped.

#[derive(Clone, Debug)]
pub struct ConvertResult {
    pub brief_source: String,
    pub diagnostics: Vec<Diag>,
}

#[derive(Clone, Debug)]
pub struct Diag {
    pub hole: Hole,
    pub line: usize, // 1-indexed
    pub col: usize,  // 1-indexed
    pub original: String,
    pub note: String,
}

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum Hole {
    SetextHeading,
    DefinitionListMultipleDefs,
    DoubleEmphasis, // **x**, __x__, ~~x~~
    EscapedSigil,
    AsteriskEmphasis, // *em* (Markdown italic)
    AltBullet,        // * or + bullet
    OrderedRenumber,
    NestIndentNormalize,
    TildeFence,
    IndentedCodeBlock,
    AltHorizontalRule,
    LinkTitleDropped,
    AutolinkRewrap,
    RefLinkInlined,
    GfmAlert,
    InlineHtml,
    HtmlBlock,
    Frontmatter,
    HtmlEntity,
    HeadingAnchorSlugged,
    BlockquoteParagraphSplit,
    TableCellPipeEscape,
    EmptyTableCell,
}

impl Hole {
    /// Stable kebab-case slug used in TODO comments and stderr report lines.
    pub fn slug(self) -> &'static str {
        match self {
            Hole::SetextHeading => "setext-heading",
            Hole::DefinitionListMultipleDefs => "definition-list-multiple-defs",
            Hole::DoubleEmphasis => "double-emphasis",
            Hole::EscapedSigil => "escaped-sigil",
            Hole::AsteriskEmphasis => "asterisk-emphasis",
            Hole::AltBullet => "alt-bullet",
            Hole::OrderedRenumber => "ordered-renumber",
            Hole::NestIndentNormalize => "nest-indent-normalize",
            Hole::TildeFence => "tilde-fence",
            Hole::IndentedCodeBlock => "indented-code-block",
            Hole::AltHorizontalRule => "alt-horizontal-rule",
            Hole::LinkTitleDropped => "link-title-dropped",
            Hole::AutolinkRewrap => "autolink-rewrap",
            Hole::RefLinkInlined => "ref-link-inlined",
            Hole::GfmAlert => "gfm-alert",
            Hole::InlineHtml => "inline-html",
            Hole::HtmlBlock => "html-block",
            Hole::Frontmatter => "frontmatter",
            Hole::HtmlEntity => "html-entity",
            Hole::HeadingAnchorSlugged => "heading-anchor-slugged",
            Hole::BlockquoteParagraphSplit => "blockquote-paragraph-split",
            Hole::TableCellPipeEscape => "table-cell-pipe-escape",
            Hole::EmptyTableCell => "empty-table-cell",
        }
    }

    /// Short human-readable label for stderr.
    pub fn message(self) -> &'static str {
        match self {
            Hole::SetextHeading => "setext heading rewritten to ATX",
            Hole::DefinitionListMultipleDefs => {
                "definition list term repeated for each of multiple Markdown definitions (Brief v0.4 limitation)"
            }
            Hole::DoubleEmphasis => "doubled emphasis marker rewritten to single",
            Hole::EscapedSigil => {
                "literal `*`/`_`/`+`/`~` in text escaped to keep Brief from opening an emphasis span"
            }
            Hole::AsteriskEmphasis => "Markdown `*italic*` rewritten to Brief `_italic_`",
            Hole::AltBullet => "`*`/`+` bullet rewritten to `-`",
            Hole::OrderedRenumber => "ordered list renumbered to sequential 1,2,3,...",
            Hole::NestIndentNormalize => "list nesting indent normalized to 2 spaces",
            Hole::TildeFence => "`~~~` fence rewritten to triple-backtick fence",
            Hole::IndentedCodeBlock => "indented code block rewritten to fenced block",
            Hole::AltHorizontalRule => "`***`/`___`/spaced rule rewritten to `---`",
            Hole::LinkTitleDropped => "link/image title attribute dropped",
            Hole::AutolinkRewrap => "autolink/bare URL wrapped in `@link[...](...)`",
            Hole::RefLinkInlined => "reference-style link resolved inline",
            Hole::GfmAlert => "GFM alert blockquote rewritten to `@callout`",
            Hole::InlineHtml => "inline HTML preserved as TODO comment",
            Hole::HtmlBlock => "HTML block preserved inside Brief block comment",
            Hole::Frontmatter => "frontmatter dropped, replaced with TODO comment",
            Hole::HtmlEntity => "HTML entity decoded to literal character",
            Hole::HeadingAnchorSlugged => "heading anchor id rewritten to `[a-z0-9-]+` slug",
            Hole::BlockquoteParagraphSplit => {
                "Markdown in-quote paragraph break rewritten to two adjacent Brief blockquotes"
            }
            Hole::TableCellPipeEscape => "`|` inside table cell escaped to `\\|`",
            Hole::EmptyTableCell => "empty Markdown table cell padded with em-dash",
        }
    }
}

use pulldown_cmark::{Event, Options, Parser, Tag, TagEnd};

/// Convert a Markdown document to Brief source.
///
/// `source_path` is used only for diagnostic location strings.
pub fn convert(input: &str, source_path: &str) -> ConvertResult {
    let mut opts = Options::empty();
    opts.insert(Options::ENABLE_TABLES);
    opts.insert(Options::ENABLE_STRIKETHROUGH);
    opts.insert(Options::ENABLE_TASKLISTS);
    opts.insert(Options::ENABLE_FOOTNOTES);
    opts.insert(Options::ENABLE_GFM);
    opts.insert(Options::ENABLE_MATH);
    opts.insert(Options::ENABLE_YAML_STYLE_METADATA_BLOCKS);
    opts.insert(Options::ENABLE_PLUSES_DELIMITED_METADATA_BLOCKS);
    opts.insert(Options::ENABLE_HEADING_ATTRIBUTES);
    opts.insert(Options::ENABLE_DEFINITION_LIST);

    let line_offsets = compute_line_offsets(input);
    let events: Vec<(Event<'_>, std::ops::Range<usize>)> =
        Parser::new_ext(input, opts).into_offset_iter().collect();

    // Pass 1: render each footnote definition's body to Brief using a fresh
    // sub-Walker so inline formatting (emphasis, links, code, ...) inside the
    // body is preserved. Markdown footnote definitions live elsewhere in the
    // source; Brief's `@footnote[body]` is inline at the reference site, so
    // we must have the rendered body ready before pass 2 visits the
    // FootnoteReference event.
    let mut footnote_defs: std::collections::BTreeMap<String, String> =
        std::collections::BTreeMap::new();
    let mut footnote_diags: Vec<Diag> = Vec::new();
    {
        let mut current_label: Option<String> = None;
        let mut current_events: Vec<(Event<'_>, std::ops::Range<usize>)> = Vec::new();
        for (event, range) in &events {
            match event {
                Event::Start(Tag::FootnoteDefinition(label)) => {
                    current_label = Some(label.to_string());
                    current_events.clear();
                }
                Event::End(TagEnd::FootnoteDefinition) => {
                    if let Some(label) = current_label.take() {
                        let mut sub = Walker::new(input, source_path, line_offsets.clone());
                        for (e, r) in current_events.drain(..) {
                            sub.visit(e, r);
                        }
                        let body = sub.out.trim().to_string();
                        footnote_diags.append(&mut sub.diags);
                        footnote_defs.insert(label, body);
                    }
                }
                _ => {
                    if current_label.is_some() {
                        current_events.push((event.clone(), range.clone()));
                    }
                }
            }
        }
    }

    // Pass 2: render the main document, skipping footnote definitions —
    // their bodies are now inlined at the FootnoteReference site.
    let mut walker = Walker::new(input, source_path, line_offsets);
    walker.footnote_defs = footnote_defs;
    walker.diags.extend(footnote_diags);
    let mut skip_until_footnote_end = false;
    for (event, range) in events {
        match (&event, skip_until_footnote_end) {
            (Event::Start(Tag::FootnoteDefinition(_)), _) => {
                skip_until_footnote_end = true;
                continue;
            }
            (Event::End(TagEnd::FootnoteDefinition), _) => {
                skip_until_footnote_end = false;
                continue;
            }
            (_, true) => continue,
            _ => {}
        }
        walker.visit(event, range);
    }
    walker.finish()
}

struct Walker<'a> {
    src: &'a str,
    _source_path: String,
    line_offsets: Vec<usize>,
    out: String,
    diags: Vec<Diag>,
    /// True while inside a paragraph (between Start(Paragraph) and End).
    in_paragraph: bool,
    /// Set while we are inside a fenced/indented code block. Suppresses
    /// inline parsing of `Event::Text` (text inside a code block is verbatim).
    in_code_block: bool,
    /// Stack of active lists.
    list_stack: Vec<ListFrame>,
    /// Stack of pending output buffers. The top of the stack is where output
    /// is actually written. On End(BlockQuote/Alert), pop and post-process
    /// (prefix lines or wrap in callout) before appending to the parent.
    out_stack: Vec<String>,
    /// Mirrors `out_stack`; top tells us how to wrap when the buffer is popped.
    container_stack: Vec<Container>,
    /// Active table accumulator (we only ever have one in flight).
    table: Option<TableState>,
    /// Active definition-list accumulator.
    dl: Option<DefinitionListState>,
    /// Stack of (dest_url, optional diagnostic to emit on End) for active links/images.
    link_stack: Vec<(String, Option<(Hole, String)>)>,
    /// Footnote labels → body text (rendered as a flat string).
    footnote_defs: std::collections::BTreeMap<String, String>,
    /// Hole TODO comment lines pending insertion before the next block.
    pending_hole_comments: Vec<String>,
    in_metadata: bool,
    metadata_buf: String,
    metadata_kind: Option<pulldown_cmark::MetadataBlockKind>,
    /// Stack of currently-open inline HTML rewrites (`<sub>`, `<sup>`, `<kbd>`).
    /// On a matching close tag we pop and emit `]`.
    html_replace_stack: Vec<HtmlInlineKind>,
    /// `Some(anchor)` between Start(Heading) and End(Heading) when the
    /// markdown source carried a `{#anchor}` attribute.
    pending_heading_anchor: Option<String>,
}

struct TableState {
    aligns: Vec<pulldown_cmark::Alignment>,
    rows: Vec<Vec<String>>,
    current_row: Vec<String>,
    current_cell: String,
    in_cell: bool,
}

struct DefinitionListState {
    /// Finalized (term_brief, definition_brief) pairs.
    items: Vec<(String, String)>,
    /// In-progress term content (writes are redirected here while `in_term`).
    current_term: String,
    /// In-progress definition content.
    current_def: String,
    /// Number of `DefinitionListDefinition` events seen for the *current*
    /// term. Used to detect "multiple definitions per term" (Task 8).
    defs_for_current_term: usize,
    in_term: bool,
    in_def: bool,
}

struct ListFrame {
    ordered: bool,
    next_index: u64,
    saw_first_item: bool,
    /// Column (1-indexed) where the *content* of items at this level starts.
    /// Used to detect non-2-space nesting in child items.
    item_content_col: usize,
}

enum Container {
    Quote,
    Alert(#[allow(dead_code)] Hole, &'static str),
    LinkPending,
    ImagePending,
    /// Paragraph buffer; on pop we flush pending HTML comments then this content.
    Paragraph,
    /// Buffer for an HtmlBlock; on End we inspect the buffered content and
    /// either rewrite `<details>` to `@details(...)/@end`, hand off to a
    /// `Details` container if the block is an opening fragment, or fall
    /// back to the existing TODO + `/* */` form.
    HtmlBlock,
    /// Active `<details>` block whose body spans multiple events (because
    /// blank lines split markdown content out of the surrounding HtmlBlock).
    /// The `summary` is captured when we open; on the closing `</details>`
    /// HtmlBlock we pop and emit `@details(summary: "..")\n[body]\n@end`.
    Details {
        summary: String,
    },
}

#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum HtmlInlineKind {
    Sub,
    Sup,
    Kbd,
}

impl HtmlInlineKind {
    fn shortcode(self) -> &'static str {
        match self {
            HtmlInlineKind::Sub => "sub",
            HtmlInlineKind::Sup => "sup",
            HtmlInlineKind::Kbd => "kbd",
        }
    }
}

impl<'a> Walker<'a> {
    fn write(&mut self, s: &str) {
        if let Some(d) = self.dl.as_mut() {
            if d.in_term {
                d.current_term.push_str(s);
                return;
            }
            if d.in_def {
                d.current_def.push_str(s);
                return;
            }
        }
        if let Some(t) = self.table.as_mut() {
            if t.in_cell {
                t.current_cell.push_str(s);
                return;
            }
        }
        if let Some(buf) = self.out_stack.last_mut() {
            buf.push_str(s);
        } else {
            self.out.push_str(s);
        }
    }
    fn write_char(&mut self, c: char) {
        if let Some(d) = self.dl.as_mut() {
            if d.in_term {
                d.current_term.push(c);
                return;
            }
            if d.in_def {
                d.current_def.push(c);
                return;
            }
        }
        if let Some(t) = self.table.as_mut() {
            if t.in_cell {
                t.current_cell.push(c);
                return;
            }
        }
        if let Some(buf) = self.out_stack.last_mut() {
            buf.push(c);
        } else {
            self.out.push(c);
        }
    }
    fn current_ends_with(&self, c: char) -> bool {
        if let Some(d) = self.dl.as_ref() {
            if d.in_term {
                return d.current_term.ends_with(c);
            }
            if d.in_def {
                return d.current_def.ends_with(c);
            }
        }
        if let Some(t) = self.table.as_ref() {
            if t.in_cell {
                return t.current_cell.ends_with(c);
            }
        }
        if let Some(buf) = self.out_stack.last() {
            buf.ends_with(c)
        } else {
            self.out.ends_with(c)
        }
    }

    fn new(src: &'a str, source_path: &str, line_offsets: Vec<usize>) -> Self {
        Walker {
            src,
            _source_path: source_path.to_string(),
            line_offsets,
            out: String::new(),
            diags: Vec::new(),
            in_paragraph: false,
            in_code_block: false,
            list_stack: Vec::new(),
            out_stack: Vec::new(),
            container_stack: Vec::new(),
            table: None,
            dl: None,
            link_stack: Vec::new(),
            footnote_defs: std::collections::BTreeMap::new(),
            pending_hole_comments: Vec::new(),
            in_metadata: false,
            metadata_buf: String::new(),
            metadata_kind: None,
            html_replace_stack: Vec::new(),
            pending_heading_anchor: None,
        }
    }

    fn visit(&mut self, event: Event<'_>, range: std::ops::Range<usize>) {
        match event {
            Event::Start(Tag::List(start)) => {
                self.flush_pending_hole_comments();
                let ordered = start.is_some();
                if let Some(n) = start {
                    if n != 1 {
                        self.push_diag(
                            Hole::OrderedRenumber,
                            range.clone(),
                            format!("ordered list started at {}; renumbered from 1", n),
                        );
                    }
                }
                // Nested list opens inside a parent Item whose text hasn't
                // closed with a newline yet. Ensure one is in place.
                if !self.list_stack.is_empty() && !self.current_ends_with('\n') {
                    self.write_char('\n');
                }
                self.list_stack.push(ListFrame {
                    ordered,
                    next_index: 1, // always renumber from 1 in Brief
                    saw_first_item: false,
                    item_content_col: 0,
                });
            }
            Event::End(TagEnd::List(_)) => {
                self.list_stack.pop();
            }
            Event::Start(Tag::Item) => {
                let depth = self.list_stack.len().saturating_sub(1);
                let (line, col) = self.pos(range.start);
                let _ = line;
                // Check for non-2-space nesting against parent frame.
                if depth > 0 {
                    let parent = &self.list_stack[depth - 1];
                    if parent.item_content_col > 0 {
                        let expected_col = parent.item_content_col;
                        if col != expected_col && col != parent.item_content_col {
                            let already = self
                                .diags
                                .iter()
                                .any(|d| d.hole == Hole::NestIndentNormalize && d.line == line);
                            if !already {
                                self.push_diag(
                                    Hole::NestIndentNormalize,
                                    range.clone(),
                                    format!(
                                        "nesting at col {} normalized to {} (2-space rule)",
                                        col, expected_col
                                    ),
                                );
                            }
                        }
                    }
                }
                let frame_ordered = self
                    .list_stack
                    .last()
                    .expect("Item without enclosing List")
                    .ordered;
                // For unordered lists, detect alt-bullet first (uses src/diags).
                if !frame_ordered {
                    let snippet = self.src.get(range.clone()).unwrap_or("");
                    let first = snippet
                        .as_bytes()
                        .iter()
                        .find(|&&b| b == b'-' || b == b'*' || b == b'+')
                        .copied();
                    if first == Some(b'*') || first == Some(b'+') {
                        self.push_diag(
                            Hole::AltBullet,
                            range.clone(),
                            format!(
                                "`{}` bullet rewritten to `-`",
                                first.map(|b| b as char).unwrap_or('?')
                            ),
                        );
                    }
                }
                let pad: String = " ".repeat(depth * 2);
                self.write(&pad);
                let frame = self
                    .list_stack
                    .last_mut()
                    .expect("Item without enclosing List");
                let marker_len: usize;
                let marker_str: String;
                if frame.ordered {
                    marker_str = format!("{}. ", frame.next_index);
                    marker_len = marker_str.len();
                    frame.next_index += 1;
                } else {
                    marker_str = "- ".to_string();
                    marker_len = 2;
                }
                frame.saw_first_item = true;
                frame.item_content_col = depth * 2 + marker_len + 1;
                self.write(&marker_str);
            }
            Event::End(TagEnd::Item) => {
                if !self.current_ends_with('\n') {
                    self.write_char('\n');
                }
            }
            Event::Start(Tag::Paragraph) => {
                self.flush_pending_hole_comments();
                self.in_paragraph = true;
                // Defer paragraph content into a buffer so we can prepend any
                // hole-comment lines collected from inline events before
                // emitting the paragraph itself.
                self.out_stack.push(String::new());
                self.container_stack.push(Container::Paragraph);
            }
            Event::End(TagEnd::Paragraph) => {
                self.in_paragraph = false;
                let body = self.out_stack.pop().expect("paragraph buffer");
                let _ = self.container_stack.pop();
                self.write(&body);
                if self.list_stack.is_empty() {
                    self.write_char('\n');
                    self.write_char('\n');
                } else {
                    // Inside a list item — no trailing blank line.
                    self.write_char('\n');
                }
            }
            Event::Start(Tag::Heading { level, id, .. }) => {
                self.flush_pending_hole_comments();
                let n = match level {
                    pulldown_cmark::HeadingLevel::H1 => 1,
                    pulldown_cmark::HeadingLevel::H2 => 2,
                    pulldown_cmark::HeadingLevel::H3 => 3,
                    pulldown_cmark::HeadingLevel::H4 => 4,
                    pulldown_cmark::HeadingLevel::H5 => 5,
                    pulldown_cmark::HeadingLevel::H6 => 6,
                };
                // Detect setext: the source span at `range` does not start with `#`.
                let snippet = self.src.get(range.clone()).unwrap_or("");
                let is_setext = !snippet.trim_start().starts_with('#');
                if is_setext {
                    self.push_diag(
                        Hole::SetextHeading,
                        range.clone(),
                        format!("rewritten to `{} ...`", "#".repeat(n)),
                    );
                }
                if let Some(raw) = id {
                    let raw = raw.to_string();
                    let safe = sluggify_anchor(&raw);
                    if safe != raw {
                        self.push_diag(
                            Hole::HeadingAnchorSlugged,
                            range.clone(),
                            format!("anchor `{}` rewritten to `{}`", raw, safe),
                        );
                    }
                    self.pending_heading_anchor = Some(safe);
                }
                for _ in 0..n {
                    self.write_char('#');
                }
                self.write_char(' ');
            }
            Event::End(TagEnd::Heading(_)) => {
                if let Some(anchor) = self.pending_heading_anchor.take() {
                    // Heading body may have ended with a trailing space from a
                    // soft break; trim before joining the anchor block.
                    while self.current_ends_with(' ') {
                        match self.out_stack.last_mut() {
                            Some(buf) => {
                                buf.pop();
                            }
                            None => {
                                self.out.pop();
                            }
                        }
                    }
                    self.write(" {#");
                    self.write(&anchor);
                    self.write_char('}');
                }
                self.write_char('\n');
            }
            Event::Start(Tag::Emphasis) => {
                // *x* (asterisk italic) is a hole; _x_ is clean.
                let first = self.src.as_bytes().get(range.start).copied();
                if first == Some(b'*') {
                    self.push_diag(
                        Hole::AsteriskEmphasis,
                        range.clone(),
                        "Markdown `*italic*` rewritten to Brief `_italic_`".into(),
                    );
                }
                self.write_char('_');
            }
            Event::End(TagEnd::Emphasis) => {
                self.write_char('_');
            }
            Event::Start(Tag::Strong) => {
                self.push_diag(
                    Hole::DoubleEmphasis,
                    range.clone(),
                    "doubled emphasis marker rewritten to single `*`".into(),
                );
                self.write_char('*');
            }
            Event::End(TagEnd::Strong) => {
                self.write_char('*');
            }
            Event::Start(Tag::Strikethrough) => {
                self.push_diag(
                    Hole::DoubleEmphasis,
                    range.clone(),
                    "doubled strikethrough rewritten to single `~`".into(),
                );
                self.write_char('~');
            }
            Event::End(TagEnd::Strikethrough) => {
                self.write_char('~');
            }
            Event::Code(s) => {
                if s.contains('`') {
                    self.write("``");
                    self.write(&s);
                    self.write("``");
                } else {
                    self.write_char('`');
                    self.write(&s);
                    self.write_char('`');
                }
            }
            Event::Start(Tag::CodeBlock(kind)) => {
                self.flush_pending_hole_comments();
                use pulldown_cmark::CodeBlockKind;
                self.in_code_block = true;
                match kind {
                    CodeBlockKind::Fenced(lang) => {
                        // Detect tilde fence by inspecting the source span.
                        let snippet = self.src.get(range.clone()).unwrap_or("");
                        if snippet.trim_start().starts_with('~') {
                            self.push_diag(
                                Hole::TildeFence,
                                range.clone(),
                                "`~~~` fence rewritten to ```` ``` ```` fence".into(),
                            );
                        }
                        self.write("```");
                        if !lang.is_empty() {
                            // Brief takes only the first whitespace-separated token.
                            let lang_token = lang.split_whitespace().next().unwrap_or("");
                            self.write(lang_token);
                        }
                        self.write_char('\n');
                    }
                    CodeBlockKind::Indented => {
                        self.push_diag(
                            Hole::IndentedCodeBlock,
                            range.clone(),
                            "indented code block rewritten to fenced block".into(),
                        );
                        self.write("```\n");
                    }
                }
            }
            Event::End(TagEnd::CodeBlock) => {
                self.in_code_block = false;
                if !self.current_ends_with('\n') {
                    self.write_char('\n');
                }
                self.write("```\n");
            }
            Event::Text(t) => {
                if self.in_metadata {
                    self.metadata_buf.push_str(&t);
                    return;
                }
                if self.in_code_block {
                    self.write(&t);
                } else {
                    let escaped = escape_brief_inline_text(&t);
                    if escaped != *t {
                        // Any sigil that needed escaping is a hole — flag it so the
                        // user can spot-check whether Brief renders the literal
                        // intent.
                        self.push_diag(
                            Hole::EscapedSigil,
                            range.clone(),
                            format!(
                                "escaped emphasis sigil(s) in literal text: {:?}",
                                t.chars().take(40).collect::<String>()
                            ),
                        );
                    }
                    self.write(&escaped);
                }
            }
            Event::TaskListMarker(checked) => {
                // v0.4 §4.3: Brief now natively supports `[x]` / `[ ]`
                // as a list-item modifier. The conversion is lossless, so
                // no diagnostic is emitted.
                self.write(if checked { "[x] " } else { "[ ] " });
            }
            Event::Start(Tag::BlockQuote(kind)) => {
                self.flush_pending_hole_comments();
                use pulldown_cmark::BlockQuoteKind;
                let container = match kind {
                    None => Container::Quote,
                    Some(BlockQuoteKind::Note) => {
                        self.push_diag(
                            Hole::GfmAlert,
                            range.clone(),
                            "GFM alert mapped to `@callout(kind: note)`".into(),
                        );
                        Container::Alert(Hole::GfmAlert, "note")
                    }
                    Some(BlockQuoteKind::Tip) => {
                        self.push_diag(
                            Hole::GfmAlert,
                            range.clone(),
                            "GFM alert mapped to `@callout(kind: tip)`".into(),
                        );
                        Container::Alert(Hole::GfmAlert, "tip")
                    }
                    Some(BlockQuoteKind::Important) => {
                        self.push_diag(
                            Hole::GfmAlert,
                            range.clone(),
                            "GFM alert mapped to `@callout(kind: important)`".into(),
                        );
                        Container::Alert(Hole::GfmAlert, "important")
                    }
                    Some(BlockQuoteKind::Warning) => {
                        self.push_diag(
                            Hole::GfmAlert,
                            range.clone(),
                            "GFM alert mapped to `@callout(kind: warning)`".into(),
                        );
                        Container::Alert(Hole::GfmAlert, "warning")
                    }
                    Some(BlockQuoteKind::Caution) => {
                        self.push_diag(
                            Hole::GfmAlert,
                            range.clone(),
                            "GFM alert mapped to `@callout(kind: caution)`".into(),
                        );
                        Container::Alert(Hole::GfmAlert, "caution")
                    }
                };
                self.out_stack.push(String::new());
                self.container_stack.push(container);
            }
            Event::End(TagEnd::BlockQuote(_)) => {
                let inner = self.out_stack.pop().expect("unbalanced quote stack");
                let container = self
                    .container_stack
                    .pop()
                    .expect("unbalanced container stack");
                let trimmed = inner.trim_end_matches('\n');
                match container {
                    Container::Quote => {
                        // Accumulate groups of consecutive non-empty lines. A blank line
                        // ends the current group; multiple blanks collapse to one
                        // separator. Brief's paragraph break inside a blockquote does not
                        // exist as a feature — it's modeled by ending the `>`-block with a
                        // blank line and starting a new one on the next non-empty line.
                        let mut groups: Vec<Vec<&str>> = Vec::new();
                        let mut cur: Vec<&str> = Vec::new();
                        for line in trimmed.split('\n') {
                            if line.is_empty() {
                                if !cur.is_empty() {
                                    groups.push(std::mem::take(&mut cur));
                                }
                                // Consecutive blanks: drop, no-op (only one separator
                                // matters between two non-empty groups).
                                continue;
                            }
                            cur.push(line);
                        }
                        if !cur.is_empty() {
                            groups.push(cur);
                        }
                        let saw_blank = groups.len() > 1;
                        for (gi, group) in groups.iter().enumerate() {
                            if gi > 0 {
                                // Empty source line — terminates the previous Brief
                                // blockquote and starts the next one. This is the line
                                // whose absence produced the original bug.
                                self.write_char('\n');
                            }
                            for line in group {
                                self.write("> ");
                                self.write(line);
                                self.write_char('\n');
                            }
                        }
                        if saw_blank {
                            // `range` is the End(TagEnd::BlockQuote(_)) event's range — the
                            // surrounding match arm parameter. It points at the close of the
                            // Markdown blockquote, which is the best signal we have for
                            // where the break originated.
                            self.push_diag(
                                Hole::BlockquoteParagraphSplit,
                                range.clone(),
                                "in-quote paragraph break rewritten to adjacent blockquotes".into(),
                            );
                        }
                    }
                    Container::Alert(_, kind) => {
                        self.write("@callout(kind: ");
                        self.write(kind);
                        self.write(")\n");
                        self.write(trimmed);
                        if !trimmed.ends_with('\n') {
                            self.write_char('\n');
                        }
                        self.write("@end\n");
                    }
                    Container::LinkPending
                    | Container::ImagePending
                    | Container::Paragraph
                    | Container::HtmlBlock
                    | Container::Details { .. } => {
                        // Should not arrive here — those containers are
                        // popped by their own End arms. Defensive no-op.
                        self.write(&inner);
                    }
                }
            }
            Event::Rule => {
                self.flush_pending_hole_comments();
                let snippet = self.src.get(range.clone()).unwrap_or("").trim();
                let is_clean_dashes = snippet == "---";
                if !is_clean_dashes {
                    self.push_diag(
                        Hole::AltHorizontalRule,
                        range.clone(),
                        format!("`{}` rewritten to `---`", snippet),
                    );
                }
                self.write("---\n");
            }
            Event::Start(Tag::Link {
                link_type,
                dest_url,
                title,
                ..
            }) => {
                use pulldown_cmark::LinkType;
                // Capture a non-empty title to emit as `title:` kwarg.
                let link_title = if title.is_empty() {
                    None
                } else {
                    Some(title.to_string())
                };
                let mut diag: Option<(Hole, String)> = None;
                match link_type {
                    LinkType::Autolink | LinkType::Email => {
                        diag = Some((
                            Hole::AutolinkRewrap,
                            format!("autolink `<{}>` wrapped in `@link[..](..)`", dest_url),
                        ));
                    }
                    LinkType::Reference
                    | LinkType::ReferenceUnknown
                    | LinkType::Collapsed
                    | LinkType::CollapsedUnknown
                    | LinkType::Shortcut
                    | LinkType::ShortcutUnknown => {
                        diag = Some((
                            Hole::RefLinkInlined,
                            "reference-style link resolved inline".into(),
                        ));
                    }
                    LinkType::Inline => {}
                    _ => {}
                }
                // Store (url, optional_title, optional_diag) via a tuple.
                // We encode the title into the url string using a sentinel separator
                // so we can reuse the existing link_stack without changing its type.
                // Instead, push title into a separate parallel stack field by
                // storing both in a combined tuple stored in out_stack label.
                // Simplest approach: store title in a new wrapper. Use an existing
                // field trick: push url\x00title so End can split on \x00.
                let url_with_title = if let Some(ref t) = link_title {
                    format!("{}\x00{}", dest_url, t)
                } else {
                    dest_url.to_string()
                };
                self.link_stack.push((url_with_title, diag));
                self.out_stack.push(String::new());
                self.container_stack.push(Container::LinkPending);
            }
            Event::End(TagEnd::Link) => {
                let text = self.out_stack.pop().expect("link buffer");
                let _ = self.container_stack.pop();
                let (url_with_title, diag) = self.link_stack.pop().expect("link stack");
                // Split url and optional title.
                let (url, opt_title) = if let Some(idx) = url_with_title.find('\x00') {
                    let (u, t) = url_with_title.split_at(idx);
                    (u.to_string(), Some(t[1..].to_string()))
                } else {
                    (url_with_title, None)
                };
                if let Some((hole, note)) = diag {
                    self.diags.push(Diag {
                        hole,
                        line: 0,
                        col: 0,
                        original: format!("[{}]({})", text, url),
                        note,
                    });
                }
                let url = brief_safe_url(&url);
                if let Some(t) = opt_title {
                    self.write("@link(title: \"");
                    self.write(&t);
                    self.write("\")[");
                    self.write(&text);
                    self.write("](");
                    self.write(&url);
                    self.write(")");
                } else {
                    self.write("@link[");
                    self.write(&text);
                    self.write("](");
                    self.write(&url);
                    self.write(")");
                }
            }
            Event::Start(Tag::Image {
                dest_url, title, ..
            }) => {
                let diag = if title.is_empty() {
                    None
                } else {
                    Some((
                        Hole::LinkTitleDropped,
                        format!("image title `{}` dropped", title),
                    ))
                };
                self.link_stack.push((dest_url.to_string(), diag));
                self.out_stack.push(String::new());
                self.container_stack.push(Container::ImagePending);
            }
            Event::End(TagEnd::Image) => {
                let alt = self.out_stack.pop().expect("image buffer");
                let _ = self.container_stack.pop();
                let (src, diag) = self.link_stack.pop().expect("link stack");
                if let Some((hole, note)) = diag {
                    self.diags.push(Diag {
                        hole,
                        line: 0,
                        col: 0,
                        original: format!("![{}]({})", alt, src),
                        note,
                    });
                }
                self.write("@image(src: \"");
                self.write(&src);
                self.write("\", alt: \"");
                self.write(&alt);
                self.write("\")[]");
            }
            Event::Start(Tag::Table(aligns)) => {
                self.flush_pending_hole_comments();
                self.table = Some(TableState {
                    aligns,
                    rows: Vec::new(),
                    current_row: Vec::new(),
                    current_cell: String::new(),
                    in_cell: false,
                });
            }
            Event::End(TagEnd::Table) => {
                if let Some(state) = self.table.take() {
                    self.emit_table(state);
                }
            }
            Event::Start(Tag::TableHead) | Event::Start(Tag::TableRow) => {
                if let Some(t) = self.table.as_mut() {
                    t.current_row = Vec::new();
                }
            }
            Event::End(TagEnd::TableHead) | Event::End(TagEnd::TableRow) => {
                if let Some(t) = self.table.as_mut() {
                    let row = std::mem::take(&mut t.current_row);
                    t.rows.push(row);
                }
            }
            Event::Start(Tag::TableCell) => {
                if let Some(t) = self.table.as_mut() {
                    t.current_cell = String::new();
                    t.in_cell = true;
                }
            }
            Event::End(TagEnd::TableCell) => {
                if let Some(t) = self.table.as_mut() {
                    let cell = std::mem::take(&mut t.current_cell);
                    t.current_row.push(cell);
                    t.in_cell = false;
                }
            }
            Event::Start(Tag::DefinitionList) => {
                self.flush_pending_hole_comments();
                // Ensure preceding blank line, same convention as paragraphs
                // and lists.
                if !self.out.is_empty() && !self.out.ends_with("\n\n") {
                    if !self.out.ends_with('\n') {
                        self.out.push('\n');
                    }
                    self.out.push('\n');
                }
                self.dl = Some(DefinitionListState {
                    items: Vec::new(),
                    current_term: String::new(),
                    current_def: String::new(),
                    defs_for_current_term: 0,
                    in_term: false,
                    in_def: false,
                });
            }
            Event::End(TagEnd::DefinitionList) => {
                // Malformed Markdown can nest definition lists; `self.dl` is
                // a single slot, so the inner `End` already consumed the
                // state and the outer `End` arrives with none. The converter
                // is lossy by design — drop the unmatched terminator instead
                // of panicking.
                let Some(state) = self.dl.take() else {
                    return;
                };
                if !state.items.is_empty() {
                    self.out.push_str("@dl\n");
                    for (term, def) in &state.items {
                        self.out.push_str(term.trim_end());
                        self.out.push('\n');
                        self.out.push_str(": ");
                        self.out.push_str(def.trim_end());
                        self.out.push('\n');
                    }
                    self.out.push_str("@end\n\n");
                }
            }
            Event::Start(Tag::DefinitionListTitle) => {
                if let Some(d) = self.dl.as_mut() {
                    d.in_term = true;
                    d.current_term.clear();
                    d.defs_for_current_term = 0;
                }
            }
            Event::End(TagEnd::DefinitionListTitle) => {
                if let Some(d) = self.dl.as_mut() {
                    d.in_term = false;
                }
            }
            Event::Start(Tag::DefinitionListDefinition) => {
                if let Some(d) = self.dl.as_mut() {
                    d.in_def = true;
                    d.current_def.clear();
                    d.defs_for_current_term += 1;
                }
                let crossed_to_two = self
                    .dl
                    .as_ref()
                    .map(|d| d.defs_for_current_term == 2)
                    .unwrap_or(false);
                if crossed_to_two {
                    self.push_diag(
                        Hole::DefinitionListMultipleDefs,
                        range.clone(),
                        "definition list term repeated for each definition (Brief v0.4 limitation)"
                            .into(),
                    );
                }
            }
            Event::End(TagEnd::DefinitionListDefinition) => {
                if let Some(d) = self.dl.as_mut() {
                    d.in_def = false;
                    let term = d.current_term.clone();
                    let def = std::mem::take(&mut d.current_def);
                    d.items.push((term, def));
                }
            }
            Event::Start(Tag::MetadataBlock(kind)) => {
                self.in_metadata = true;
                self.metadata_buf.clear();
                self.metadata_kind = Some(kind);
            }
            Event::End(TagEnd::MetadataBlock(_)) => {
                use pulldown_cmark::MetadataBlockKind;
                self.in_metadata = false;
                let kind = self.metadata_kind.take();
                let body = std::mem::take(&mut self.metadata_buf);
                match kind {
                    Some(MetadataBlockKind::PlusesStyle) => {
                        // TOML markdown frontmatter has a clean Brief equivalent;
                        // emit it directly with no hole diagnostic.
                        self.write("+++\n");
                        self.write(&body);
                        if !body.ends_with('\n') {
                            self.write_char('\n');
                        }
                        self.write("+++\n\n");
                    }
                    _ => {
                        self.push_diag(
                            Hole::Frontmatter,
                            range.clone(),
                            "frontmatter dropped, replaced with TODO comment".into(),
                        );
                        // Flush the pending hole comment (just pushed by push_diag)
                        // so it appears immediately at the frontmatter site.
                        self.flush_pending_hole_comments();
                    }
                }
            }
            Event::Start(Tag::HtmlBlock) => {
                // Buffer the block's content; on End we either rewrite a
                // recognized `<details>` shape or fall back to the
                // existing TODO + `/* */` comment form.
                self.out_stack.push(String::new());
                self.container_stack.push(Container::HtmlBlock);
            }
            Event::End(TagEnd::HtmlBlock) => {
                let buf = self.out_stack.pop().expect("html block buffer");
                let _ = self.container_stack.pop();
                match classify_details_block(&buf) {
                    DetailsShape::Closed { summary, body } => {
                        self.write("@details(summary: \"");
                        self.write(&escape_brief_string(&summary));
                        self.write("\")\n");
                        let body = body.trim_matches('\n');
                        if !body.is_empty() {
                            self.write(body);
                            self.write_char('\n');
                        }
                        self.write("@end\n\n");
                    }
                    DetailsShape::Open { summary } => {
                        // The `</details>` will arrive in a later HtmlBlock.
                        // Stage a Details container that captures any
                        // blocks rendered in between.
                        self.out_stack.push(String::new());
                        self.container_stack.push(Container::Details { summary });
                    }
                    DetailsShape::Close => {
                        // Pop the matching Details container, if any.
                        let mut closed = false;
                        if matches!(self.container_stack.last(), Some(Container::Details { .. })) {
                            let body = self.out_stack.pop().expect("details body buffer");
                            let container = self.container_stack.pop().expect("details container");
                            if let Container::Details { summary } = container {
                                self.write("@details(summary: \"");
                                self.write(&escape_brief_string(&summary));
                                self.write("\")\n");
                                let body = body.trim_matches('\n');
                                if !body.is_empty() {
                                    self.write(body);
                                    self.write_char('\n');
                                }
                                self.write("@end\n\n");
                                closed = true;
                            }
                        }
                        if !closed {
                            // Stray `</details>` with no opener on the
                            // stack — fall back to the comment form.
                            self.fallback_html_block(range.clone(), &buf);
                        }
                    }
                    DetailsShape::Unknown => {
                        self.fallback_html_block(range.clone(), &buf);
                    }
                }
            }
            Event::Html(s) => {
                // Block-level HTML content (between Start/End of HtmlBlock).
                self.write(&s);
            }
            Event::InlineHtml(s) => {
                let trimmed = s.trim();
                if let Some(kind) = classify_inline_html_open(trimmed) {
                    self.html_replace_stack.push(kind);
                    self.write_char('@');
                    self.write(kind.shortcode());
                    self.write_char('[');
                    return;
                }
                if let Some(kind) = classify_inline_html_close(trimmed) {
                    if self.html_replace_stack.last().copied() == Some(kind) {
                        self.html_replace_stack.pop();
                        self.write_char(']');
                        return;
                    }
                    // Mismatched close — fall through to TODO so we don't
                    // emit a stray `]` that would corrupt the output.
                }
                if is_inline_br(trimmed) {
                    // Brief hard break: backslash at end of line.
                    self.write_char('\\');
                    self.write_char('\n');
                    return;
                }
                let snippet = s.to_string();
                self.push_diag(
                    Hole::InlineHtml,
                    range.clone(),
                    format!("`{}` preserved as TODO comment", snippet.trim()),
                );
                // push_diag already queued a pending_hole_comments entry;
                // it will be flushed before the next block-level event.
            }
            Event::FootnoteReference(label) => {
                let body = self
                    .footnote_defs
                    .get(label.as_ref())
                    .cloned()
                    .unwrap_or_else(|| format!("??: {}", label));
                self.write("@footnote[");
                self.write(&body);
                self.write("]");
            }
            Event::SoftBreak => {
                self.write_char('\n');
            }
            Event::HardBreak => {
                self.write_char('\\');
                self.write_char('\n');
            }
            Event::InlineMath(s) => {
                self.write("@math[");
                self.write(&s);
                self.write_char(']');
            }
            Event::DisplayMath(s) => {
                let body = s.trim_matches('\n');
                self.write("@math\n");
                self.write(body);
                self.write_char('\n');
                self.write("@end");
            }
            _ => {
                // Other events handled in subsequent tasks.
            }
        }
    }

    fn finish(mut self) -> ConvertResult {
        // Drain any TODO comments queued by the last block — there's no
        // subsequent Start event to flush them.
        self.flush_pending_hole_comments();
        // Trim trailing blank lines down to a single newline.
        while self.out.ends_with("\n\n") {
            self.out.pop();
        }
        if !self.out.is_empty() && !self.out.ends_with('\n') {
            self.out.push('\n');
        }
        ConvertResult {
            brief_source: self.out,
            diagnostics: self.diags,
        }
    }

    /// Convert a byte offset into 1-indexed (line, column).
    #[allow(dead_code)] // used by later tasks
    fn pos(&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[line - 1];
                (line, offset - line_start + 1)
            }
        }
    }

    #[allow(dead_code)] // used by later tasks
    fn push_diag(&mut self, hole: Hole, range: std::ops::Range<usize>, note: String) {
        let (line, col) = self.pos(range.start);
        let original = self
            .src
            .get(range.clone())
            .unwrap_or("")
            .chars()
            .take(80)
            .collect::<String>();
        self.diags.push(Diag {
            hole,
            line,
            col,
            original,
            note: note.clone(),
        });
        // Surface every hole as a `// TODO[B-hole:slug]:` line so a reviewer
        // can grep the converted corpus. Flushed before the next block.
        self.pending_hole_comments
            .push(format!("// TODO[B-hole:{}]: {}", hole.slug(), note));
    }

    fn flush_pending_hole_comments(&mut self) {
        for c in std::mem::take(&mut self.pending_hole_comments) {
            // Write to top buffer (or `out`).
            if let Some(buf) = self.out_stack.last_mut() {
                buf.push_str(&c);
                buf.push('\n');
            } else {
                self.out.push_str(&c);
                self.out.push('\n');
            }
        }
    }

    /// Emit a buffered HTML block as the existing TODO + `/* */` comment
    /// fallback. Used when the block isn't a recognizable `<details>`.
    fn fallback_html_block(&mut self, range: std::ops::Range<usize>, buf: &str) {
        self.push_diag(
            Hole::HtmlBlock,
            range,
            "HTML block preserved inside Brief block comment".into(),
        );
        // Flush the pending hole comment (just pushed by push_diag) so it
        // appears immediately before the block comment, not deferred.
        self.flush_pending_hole_comments();
        self.write("/*\n");
        // Brief block comments don't nest; sanitize any embedded `*/` so
        // the comment terminates only where we want it to.
        let sanitized = buf.replace("*/", "* /");
        self.write(&sanitized);
        if !sanitized.ends_with('\n') {
            self.write_char('\n');
        }
        self.write("*/\n");
    }

    fn emit_table(&mut self, state: TableState) {
        use pulldown_cmark::Alignment;
        let needs_align = state.aligns.iter().any(|a| !matches!(a, Alignment::None));
        if needs_align {
            self.write("@t(align: [");
            let parts: Vec<&str> = state
                .aligns
                .iter()
                .map(|a| match a {
                    Alignment::None | Alignment::Left => "left",
                    Alignment::Center => "center",
                    Alignment::Right => "right",
                })
                .collect();
            self.write(&parts.join(", "));
            self.write("])\n");
        } else {
            self.write("@t\n");
        }
        let mut saw_pipe_escape = false;
        for row in &state.rows {
            self.write("|");
            for (i, cell) in row.iter().enumerate() {
                self.write(" ");
                let trimmed = cell.trim();
                let (escaped, escaped_pipe) = if trimmed.is_empty() {
                    self.diags.push(Diag {
                        hole: Hole::EmptyTableCell,
                        line: 0,
                        col: 0,
                        original: String::new(),
                        note: "empty Markdown table cell padded with `—`".into(),
                    });
                    ("—".to_string(), false)
                } else {
                    escape_table_cell(trimmed)
                };
                if escaped_pipe {
                    saw_pipe_escape = true;
                }
                self.write(&escaped);
                if i + 1 < row.len() {
                    self.write(" |");
                }
            }
            self.write("\n");
        }
        if saw_pipe_escape {
            self.diags.push(Diag {
                hole: Hole::TableCellPipeEscape,
                line: 0,
                col: 0,
                original: String::new(),
                note: "`|` inside table cell escaped to `\\|`".into(),
            });
        }
    }
}

/// Coerce an arbitrary heading id string into Brief's `[a-z0-9-]+` form.
/// Lowercases ASCII, replaces every other char with `-`, collapses runs,
/// strips leading/trailing `-`. Falls back to `"section"` when the input
/// has no usable characters.
fn sluggify_anchor(raw: &str) -> String {
    let mut out = String::with_capacity(raw.len());
    let mut last_dash = true;
    for ch in raw.chars() {
        let lo = ch.to_ascii_lowercase();
        if lo.is_ascii_lowercase() || lo.is_ascii_digit() {
            out.push(lo);
            last_dash = false;
        } else if !last_dash {
            out.push('-');
            last_dash = true;
        }
    }
    while out.ends_with('-') {
        out.pop();
    }
    if out.is_empty() {
        return "section".to_string();
    }
    out
}

/// Classify an `Event::InlineHtml` payload as an opening tag we know how
/// to rewrite. Returns `None` for everything else (closing tags,
/// self-closing tags, unrecognized fragments) — the caller handles those.
fn classify_inline_html_open(s: &str) -> Option<HtmlInlineKind> {
    let t = s.trim().to_ascii_lowercase();
    match t.as_str() {
        "<sub>" => Some(HtmlInlineKind::Sub),
        "<sup>" => Some(HtmlInlineKind::Sup),
        "<kbd>" => Some(HtmlInlineKind::Kbd),
        _ => None,
    }
}

fn classify_inline_html_close(s: &str) -> Option<HtmlInlineKind> {
    let t = s.trim().to_ascii_lowercase();
    match t.as_str() {
        "</sub>" => Some(HtmlInlineKind::Sub),
        "</sup>" => Some(HtmlInlineKind::Sup),
        "</kbd>" => Some(HtmlInlineKind::Kbd),
        _ => None,
    }
}

fn is_inline_br(s: &str) -> bool {
    let t = s.trim().to_ascii_lowercase();
    matches!(t.as_str(), "<br>" | "<br/>" | "<br />")
}

/// Escape unescaped `|` characters in cell content so Brief's row
/// splitter sees one cell. Returns `(escaped_string, did_any_escape)`.
///
/// We deliberately do NOT track whether we are inside a backtick code
/// span here. After Phase B (parser backtick-aware split), `|` inside a
/// backtick span is already opaque to the row splitter, but `\|` outside
/// a code span is still the canonical Brief escape for a literal `|`.
/// Always escaping is simpler and never wrong.
fn escape_table_cell(s: &str) -> (String, bool) {
    let mut out = String::with_capacity(s.len());
    let mut escaped = false;
    let mut prev_backslash = false;
    for ch in s.chars() {
        if ch == '|' && !prev_backslash {
            out.push('\\');
            out.push('|');
            escaped = true;
            prev_backslash = false;
            continue;
        }
        prev_backslash = ch == '\\' && !prev_backslash;
        out.push(ch);
    }
    (out, escaped)
}

/// Escape a summary string for use inside `@details(summary: "...")`.
fn escape_brief_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for ch in s.chars() {
        match ch {
            '\\' => out.push_str("\\\\"),
            '"' => out.push_str("\\\""),
            '\n' | '\r' => out.push(' '),
            _ => out.push(ch),
        }
    }
    out
}

/// Try to recognize a `<details>` HTML fragment.
///
/// Returns `DetailsShape::Closed` when the buffer fully wraps a
/// `<details>...</details>` block; `DetailsShape::Open` when the buffer
/// is the *opening* fragment of a multi-event `<details>` block (the
/// closing `</details>` will arrive in a later HtmlBlock); `Unknown`
/// otherwise.
fn classify_details_block(buf: &str) -> DetailsShape {
    let trimmed = buf.trim();
    let lower = trimmed.to_ascii_lowercase();
    let starts_open = lower.starts_with("<details>")
        || lower.starts_with("<details ")
        || lower.starts_with("<details\n");
    let only_close = lower == "</details>" || lower.starts_with("</details>");
    if only_close && !starts_open {
        // Bare close fragment; caller will pop a Details container.
        return DetailsShape::Close;
    }
    if !starts_open {
        return DetailsShape::Unknown;
    }
    let after_open = match find_after_open_tag(trimmed, "details") {
        Some(idx) => idx,
        None => return DetailsShape::Unknown,
    };
    let inner = &trimmed[after_open..];
    // Strip a single optional leading newline.
    let inner = inner.strip_prefix('\n').unwrap_or(inner);
    let summary = extract_summary(inner);
    let body_start = match summary.as_ref() {
        Some((_, end)) => *end,
        None => 0,
    };
    let after_summary = &inner[body_start..];
    // Look for matching `</details>` at the end of the buffer (case-insensitive).
    let lower_after = after_summary.to_ascii_lowercase();
    if let Some(close_idx) = lower_after.rfind("</details>") {
        let body = after_summary[..close_idx].trim_matches('\n').to_string();
        let summary_text = summary.map(|((s, _), _)| s).unwrap_or_default();
        DetailsShape::Closed {
            summary: summary_text,
            body,
        }
    } else {
        // Opener without close — defer body to a Details container.
        let summary_text = summary.map(|((s, _), _)| s).unwrap_or_default();
        DetailsShape::Open {
            summary: summary_text,
        }
    }
}

enum DetailsShape {
    Closed { summary: String, body: String },
    Open { summary: String },
    Close,
    Unknown,
}

/// Return the byte index immediately after the opening tag for `name`
/// (case-insensitive), e.g. the index after `<details>` or `<details ...>`.
fn find_after_open_tag(s: &str, name: &str) -> Option<usize> {
    let lower = s.to_ascii_lowercase();
    let needle = format!("<{}", name);
    let start = lower.find(&needle)?;
    let rest = &s[start + needle.len()..];
    let close = rest.find('>')?;
    Some(start + needle.len() + close + 1)
}

/// Pull a `<summary>...</summary>` out of `s`. Returns `((text, byte_len),
/// end_byte_offset_of_close_tag)` when found.
#[allow(clippy::type_complexity)]
fn extract_summary(s: &str) -> Option<((String, usize), usize)> {
    let lower = s.to_ascii_lowercase();
    let open_idx = lower.find("<summary")?;
    let after_open_attrs = &s[open_idx..];
    let gt = after_open_attrs.find('>')?;
    let body_start = open_idx + gt + 1;
    let after_body = &s[body_start..];
    let lower_after = after_body.to_ascii_lowercase();
    let close_rel = lower_after.find("</summary>")?;
    let summary_text = strip_tags(&after_body[..close_rel]).trim().to_string();
    let close_end = body_start + close_rel + "</summary>".len();
    Some(((summary_text, close_end - open_idx), close_end))
}

/// Rough HTML-to-text: drops anything that looks like a tag.
fn strip_tags(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut in_tag = false;
    for ch in s.chars() {
        match ch {
            '<' => in_tag = true,
            '>' => in_tag = false,
            _ if !in_tag => out.push(ch),
            _ => {}
        }
    }
    out
}

/// Walk `s` and prepend `\` before every `*`/`_`/`+`/`~` for which
/// Brief's `is_open_marker_at` predicate fires — those would otherwise
/// open an emphasis span in the converted Brief output. Markdown's
/// parser already paired any *real* emphasis as `Start/End(Emphasis)`,
/// so any sigil reaching us inside `Event::Text` was a literal in the
/// source.
///
/// Pulldown-cmark may split text around strikethrough/emphasis candidates
/// (e.g. `~10` becomes two events: `"~"` and `"10..."`). A sigil at the
/// *end* of the text string has no visible next-char in this fragment, but
/// when the Brief output is assembled the next event's first char follows
/// immediately — making the sigil a valid opener in Brief. We therefore
/// also escape sigils that have valid left-context and sit at the end of
/// the string (conservatively treating the boundary as "next char unknown").
fn escape_brief_inline_text(s: &str) -> String {
    use crate::inline::{is_inline_sigil, is_open_marker_at, is_punct};
    let bytes = s.as_bytes();
    let mut out = String::with_capacity(s.len());
    let mut i = 0usize;
    while i < bytes.len() {
        let b = bytes[i];
        if matches!(b, b'*' | b'_' | b'+' | b'~') {
            // Check the shared predicate first (handles mid-string case).
            let should_escape = is_open_marker_at(bytes, i) || {
                // Also escape a sigil at the end of the text fragment if it
                // has valid left-context: the next text event may start with
                // a non-space char, making this a valid emphasis opener in
                // the concatenated Brief output.
                let is_last = i + 1 == bytes.len();
                if is_last {
                    let prev = if i == 0 { None } else { Some(bytes[i - 1]) };
                    let prev_ok = match prev {
                        None => true,
                        Some(b' ') => true,
                        Some(pb) if is_inline_sigil(pb) => true,
                        Some(pb) if is_punct(pb) => true,
                        _ => false,
                    };
                    // prev must not be the same marker (doubled-marker rule)
                    let not_doubled = prev != Some(b);
                    prev_ok && not_doubled
                } else {
                    false
                }
            };
            if should_escape {
                out.push('\\');
                out.push(b as char);
                let w = s[i..].chars().next().map_or(1, |c| c.len_utf8());
                i += w;
                continue;
            }
        }
        let w = s[i..].chars().next().map_or(1, |c| c.len_utf8());
        out.push_str(&s[i..i + w]);
        i += w;
    }
    out
}

/// Make a URL safe for Brief's `@link[text](url)` sugar. The compiler scans
/// the `(url)` with balanced-paren counting, so balanced parens pass through
/// verbatim; unbalanced ones would swallow or truncate the URL and must be
/// percent-encoded.
fn brief_safe_url(url: &str) -> String {
    let mut depth = 0i64;
    let mut balanced = true;
    for b in url.bytes() {
        match b {
            b'(' => depth += 1,
            b')' => {
                depth -= 1;
                if depth < 0 {
                    balanced = false;
                    break;
                }
            }
            _ => {}
        }
    }
    if balanced && depth == 0 {
        return url.to_string();
    }
    url.replace('(', "%28").replace(')', "%29")
}

fn compute_line_offsets(s: &str) -> Vec<usize> {
    let mut v = vec![0usize];
    for (i, b) in s.bytes().enumerate() {
        if b == b'\n' {
            v.push(i + 1);
        }
    }
    v
}

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

    #[test]
    fn converts_toml_frontmatter_cleanly() {
        let md = "+++\ntitle = \"hi\"\nn = 3\n+++\n\n# Doc\nbody\n";
        let res = convert(md, "in.md");
        assert!(
            !res.diagnostics.iter().any(|d| d.hole == Hole::Frontmatter),
            "{:?}",
            res.diagnostics
        );
        assert!(
            res.brief_source.starts_with("+++\n"),
            "got: {}",
            res.brief_source
        );
        assert!(res.brief_source.contains("title = \"hi\""));
        assert!(res.brief_source.contains("n = 3"));
        assert!(res.brief_source.contains("\n+++\n"));
        assert!(res.brief_source.contains("# Doc"));
    }

    #[test]
    fn converts_yaml_frontmatter_as_hole() {
        let md = "---\ntitle: hi\n---\n\n# Doc\n";
        let res = convert(md, "in.md");
        assert!(
            res.diagnostics.iter().any(|d| d.hole == Hole::Frontmatter),
            "{:?}",
            res.diagnostics
        );
        assert!(
            res.brief_source.contains("// TODO[B-hole:frontmatter]"),
            "{}",
            res.brief_source
        );
    }

    #[test]
    fn converted_toml_frontmatter_round_trips_through_compiler() {
        let md = "+++\ntitle = \"hi\"\n+++\n\n# Doc\n";
        let res = convert(md, "in.md");
        let src = crate::span::SourceMap::new("in.brf", res.brief_source.clone());
        let toks = crate::lexer::lex(&src).expect("lex ok");
        let (doc, diags) = crate::parser::parse(toks, &src);
        assert!(diags.is_empty(), "{:?}\n---\n{}", diags, res.brief_source);
        assert!(doc.metadata.is_some());
    }

    #[test]
    fn tilde_before_digit_inside_emphasis_round_trips() {
        // Production report pattern #1: `*…patch exceeds ~10 ops, any value
        // exceeds ~50 lines…*` opens a strikethrough on `~10` that never
        // closes, producing B0204 + B0207 in Brief.
        let md = "*patch exceeds ~10 ops, any value exceeds ~50 lines*\n";
        let res = convert(md, "in.md");
        let src = crate::span::SourceMap::new("in.brf", res.brief_source.clone());
        let toks = crate::lexer::lex(&src).expect("lex ok");
        let (_doc, diags) = crate::parser::parse(toks, &src);
        let errors: Vec<_> = diags
            .iter()
            .filter(|d| d.severity == crate::diag::Severity::Error)
            .collect();
        assert!(
            errors.is_empty(),
            "converter output failed to compile: {:?}\nbrief: {}",
            errors,
            res.brief_source
        );
    }

    #[test]
    fn asterisk_in_heading_text_round_trips() {
        // Production report pattern #2: `### 8.6 Set an attribute (href, aria-*, …)`.
        let md = "### 8.6 Set an attribute (href, aria-*, …)\n";
        let res = convert(md, "in.md");
        let src = crate::span::SourceMap::new("in.brf", res.brief_source.clone());
        let toks = crate::lexer::lex(&src).expect("lex ok");
        let (_doc, diags) = crate::parser::parse(toks, &src);
        let errors: Vec<_> = diags
            .iter()
            .filter(|d| d.severity == crate::diag::Severity::Error)
            .collect();
        assert!(
            errors.is_empty(),
            "{:?}\nbrief: {}",
            errors,
            res.brief_source
        );
        assert!(
            res.brief_source.contains(r"aria-\*"),
            "brief: {}",
            res.brief_source
        );
    }

    #[test]
    fn empty_blockquote_line_splits_into_adjacent_quotes() {
        let md = "> first paragraph\n> still first\n>\n> second paragraph\n";
        let res = convert(md, "in.md");
        let src = crate::span::SourceMap::new("in.brf", res.brief_source.clone());
        let toks = crate::lexer::lex(&src).expect("lex ok");
        let (doc, diags) = crate::parser::parse(toks, &src);
        let errors: Vec<_> = diags
            .iter()
            .filter(|d| d.severity == crate::diag::Severity::Error)
            .collect();
        assert!(
            errors.is_empty(),
            "{:?}\nbrief: {}",
            errors,
            res.brief_source
        );
        assert!(
            res.diagnostics
                .iter()
                .any(|d| d.hole == Hole::BlockquoteParagraphSplit),
            "{:?}",
            res.diagnostics
        );
        let blockquote_count = doc
            .blocks
            .iter()
            .filter(|b| matches!(b, crate::ast::Block::Blockquote { .. }))
            .count();
        assert_eq!(
            blockquote_count, 2,
            "expected two adjacent blockquotes; got blocks {:?}\nbrief: {}",
            doc.blocks, res.brief_source
        );
    }

    #[test]
    fn pipe_in_cell_is_escaped() {
        // Production report pattern #4.
        let md = "| Kind | Example |\n| --- | --- |\n| separator | \"semantic\"\\|\"utility\" |\n";
        let res = convert(md, "in.md");
        let src = crate::span::SourceMap::new("in.brf", res.brief_source.clone());
        let toks = crate::lexer::lex(&src).expect("lex ok");
        let (_doc, diags) = crate::parser::parse(toks, &src);
        let errors: Vec<_> = diags
            .iter()
            .filter(|d| d.severity == crate::diag::Severity::Error)
            .collect();
        assert!(
            errors.is_empty(),
            "{:?}\nbrief: {}",
            errors,
            res.brief_source
        );
        assert!(
            res.brief_source.contains(r#""semantic"\|"utility""#),
            "brief: {}",
            res.brief_source
        );
    }

    #[test]
    fn empty_trailing_cell_is_padded() {
        // Production report pattern #5.
        let md = "| Value | Type | Note |\n| --- | --- | --- |\n| true/false | Boolean |  |\n";
        let res = convert(md, "in.md");
        let src = crate::span::SourceMap::new("in.brf", res.brief_source.clone());
        let toks = crate::lexer::lex(&src).expect("lex ok");
        let (_doc, diags) = crate::parser::parse(toks, &src);
        let errors: Vec<_> = diags
            .iter()
            .filter(|d| d.severity == crate::diag::Severity::Error)
            .collect();
        assert!(
            errors.is_empty(),
            "{:?}\nbrief: {}",
            errors,
            res.brief_source
        );
        assert!(
            res.brief_source.contains("—"),
            "brief: {}",
            res.brief_source
        );
        assert!(
            res.diagnostics
                .iter()
                .any(|d| d.hole == Hole::EmptyTableCell),
            "{:?}",
            res.diagnostics
        );
    }

    #[test]
    fn double_emphasis_emits_inline_todo_comment() {
        let md = "**bold text** in a paragraph\n";
        let res = convert(md, "in.md");
        assert!(
            res.brief_source.contains("// TODO[B-hole:double-emphasis]"),
            "brief: {}",
            res.brief_source
        );
    }

    #[test]
    fn last_block_hole_flushes_at_eof() {
        let md = "trailing **bold** at the end of doc\n";
        let res = convert(md, "in.md");
        assert!(
            res.brief_source.contains("// TODO[B-hole:double-emphasis]"),
            "EOF flush dropped the trailing hole's comment\nbrief: {}",
            res.brief_source
        );
    }
}