lex-babel 0.19.2

//! Converts a nested IR tree structure into a flat event stream.
//!
//! # The High-Level Concept
//!
//! Traversing the nested document structure in pre-order lets us emit a
//! sequence of start/content/end events that can later be reassembled into
//! the original tree. Each container node produces its own start/end markers
//! and then recurses into children so the flat stream preserves the original
//! nesting.
//!
//! # The Algorithm
//!
//! 1. **Initialization:**
//!    - Create an empty event vector
//!    - Begin walking from the root `DocNode`
//!
//! 2. **Entering Containers:**
//!    - Emit the corresponding `Start*` event
//!    - Emit inline content, if any
//!    - Recurse into child nodes
//!
//! 3. **Handling Inline Nodes:**
//!    - Inline-only nodes become a single `Inline` event in place
//!
//! 4. **Exiting Containers:**
//!    - Emit the matching `End*` event once children are processed
//!
//! 5. **Completion:**
//!    - Return the accumulated event stream
//!
//! This mirrors the reverse process performed in `flat_to_nested`, ensuring
//! round-trippable conversions between the nested IR and flat event stream.

use crate::ir::events::Event;
use crate::ir::nodes::{
    Annotation, Definition, DocNode, Document, Heading, InlineContent, List, ListItem, Paragraph,
    Table, TableCell, TableRow, Verbatim,
};

/// Converts a `DocNode` tree to a flat vector of `Event`s.
pub fn tree_to_events(root_node: &DocNode) -> Vec<Event> {
    let mut events = Vec::new();
    walk_node(root_node, &mut events);
    events
}

fn walk_node(node: &DocNode, events: &mut Vec<Event>) {
    match node {
        DocNode::Document(Document { children, .. }) => {
            events.push(Event::StartDocument);
            // Phase 3b (#614): `document_annotations` is no longer
            // flattened into the event stream as a synthetic
            // `frontmatter` annotation here. Format-specific
            // serializers that need a packed YAML preamble (currently
            // just markdown) read `document_annotations` from the IR
            // Document directly. The IR is the single source of truth.
            for child in children {
                walk_node(child, events);
            }
            events.push(Event::EndDocument);
        }
        DocNode::Heading(Heading {
            level,
            content,
            children,
        }) => {
            events.push(Event::StartHeading(*level));
            emit_inlines(content, events);
            if !children.is_empty() {
                events.push(Event::StartContent);
                for child in children {
                    walk_node(child, events);
                }
                events.push(Event::EndContent);
            }
            events.push(Event::EndHeading(*level));
        }
        DocNode::Paragraph(Paragraph { content }) => {
            events.push(Event::StartParagraph);
            emit_inlines(content, events);
            events.push(Event::EndParagraph);
        }
        DocNode::List(List {
            items,
            ordered,
            style,
            form,
        }) => {
            events.push(Event::StartList {
                ordered: *ordered,
                style: *style,
                form: *form,
            });
            for item in items {
                walk_list_item(item, events);
            }
            events.push(Event::EndList);
        }
        DocNode::ListItem(_) => {
            // List items are emitted by the surrounding list handler.
            if cfg!(debug_assertions) {
                unreachable!("ListItem should only be emitted by List");
            }
        }
        DocNode::Definition(Definition { term, description }) => {
            events.push(Event::StartDefinition);
            events.push(Event::StartDefinitionTerm);
            emit_inlines(term, events);
            events.push(Event::EndDefinitionTerm);
            events.push(Event::StartDefinitionDescription);
            if !description.is_empty() {
                events.push(Event::StartContent);
                for child in description {
                    walk_node(child, events);
                }
                events.push(Event::EndContent);
            }
            events.push(Event::EndDefinitionDescription);
            events.push(Event::EndDefinition);
        }
        DocNode::Verbatim(Verbatim {
            subject,
            subject_href,
            language,
            content,
            parameters,
        }) => {
            events.push(Event::StartVerbatim {
                language: language.clone(),
                subject: subject.clone(),
                subject_href: subject_href.clone(),
                parameters: parameters.clone(),
            });
            events.push(Event::Inline(InlineContent::Text(content.clone())));
            events.push(Event::EndVerbatim);
        }
        DocNode::Annotation(Annotation {
            label,
            parameters,
            content,
            form,
        }) => {
            // Post-refac/label cleanup: the bare-label metadata
            // whitelist (`author`, `title`, …) that used to live here
            // and synthesize `lex-metadata:<label>` verbatim events is
            // gone. After #570 Phase 3b activated `NormalizeLabels`,
            // no production path produces IR annotations with those
            // bare labels — they're either rewritten to canonical
            // `lex.metadata.*` and promoted into the `frontmatter`
            // annotation by `from_lex_document`, or they come from
            // markdown imports as a single packed `frontmatter`
            // annotation. The HTML/Markdown serializers handle the
            // `frontmatter` label directly in their `StartAnnotation`
            // arms.
            events.push(Event::StartAnnotation {
                label: label.clone(),
                parameters: parameters.clone(),
                form: *form,
            });
            if !content.is_empty() {
                events.push(Event::StartContent);
                for child in content {
                    walk_node(child, events);
                }
                events.push(Event::EndContent);
            }
            events.push(Event::EndAnnotation {
                label: label.clone(),
            });
        }
        DocNode::Table(Table {
            rows,
            header,
            caption,
            footnotes,
            fullwidth,
        }) => {
            events.push(Event::StartTable {
                caption: caption.clone(),
                fullwidth: *fullwidth,
            });
            for row in header {
                walk_table_row(row, events, true);
            }
            for row in rows {
                walk_table_row(row, events, false);
            }
            if !footnotes.is_empty() {
                events.push(Event::StartTableFootnotes);
                for node in footnotes {
                    walk_node(node, events);
                }
                events.push(Event::EndTableFootnotes);
            }
            events.push(Event::EndTable);
        }
        DocNode::Image(image) => events.push(Event::Image(image.clone())),
        DocNode::Video(video) => events.push(Event::Video(video.clone())),
        DocNode::Audio(audio) => events.push(Event::Audio(audio.clone())),
        DocNode::Inline(inline) => events.push(Event::Inline(inline.clone())),
    }
}

fn walk_table_row(row: &TableRow, events: &mut Vec<Event>, header: bool) {
    events.push(Event::StartTableRow { header });
    for cell in &row.cells {
        walk_table_cell(cell, events);
    }
    events.push(Event::EndTableRow);
}

fn walk_table_cell(cell: &TableCell, events: &mut Vec<Event>) {
    events.push(Event::StartTableCell {
        header: cell.header,
        align: cell.align,
        colspan: cell.colspan,
        rowspan: cell.rowspan,
    });
    if !cell.content.is_empty() {
        events.push(Event::StartContent);
        for child in &cell.content {
            walk_node(child, events);
        }
        events.push(Event::EndContent);
    }
    events.push(Event::EndTableCell);
}

fn walk_list_item(item: &ListItem, events: &mut Vec<Event>) {
    events.push(Event::StartListItem);
    emit_inlines(&item.content, events);
    if !item.children.is_empty() {
        events.push(Event::StartContent);
        for child in &item.children {
            walk_node(child, events);
        }
        events.push(Event::EndContent);
    }
    events.push(Event::EndListItem);
}

fn emit_inlines(inlines: &[InlineContent], events: &mut Vec<Event>) {
    for inline in inlines {
        events.push(Event::Inline(inline.clone()));
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::common::flat_to_nested::events_to_tree;
    use crate::ir::nodes::{LabelForm, ListForm, ListStyle};

    fn sample_tree() -> DocNode {
        DocNode::Document(Document {
            title: None,
            subtitle: None,
            children: vec![
                DocNode::Heading(Heading {
                    level: 2,
                    content: vec![InlineContent::Text("Intro".to_string())],
                    children: vec![DocNode::Paragraph(Paragraph {
                        content: vec![InlineContent::Text("Welcome".to_string())],
                    })],
                }),
                DocNode::List(List {
                    items: vec![ListItem {
                        content: vec![InlineContent::Text("Item".to_string())],
                        children: vec![DocNode::Verbatim(Verbatim {
                            subject: None,
                            subject_href: None,
                            language: Some("rust".to_string()),
                            content: "fn main() {}".to_string(),
                            parameters: Vec::new(),
                        })],
                    }],
                    ordered: false,
                    style: ListStyle::Bullet,
                    form: ListForm::Short,
                }),
                DocNode::Definition(Definition {
                    term: vec![InlineContent::Text("Term".to_string())],
                    description: vec![DocNode::Paragraph(Paragraph {
                        content: vec![InlineContent::Text("Definition".to_string())],
                    })],
                }),
                DocNode::Annotation(Annotation {
                    label: "note".to_string(),
                    parameters: vec![("key".to_string(), "value".to_string())],
                    content: vec![DocNode::Paragraph(Paragraph {
                        content: vec![InlineContent::Text("Body".to_string())],
                    })],
                    form: LabelForm::Canonical,
                }),
            ],
            document_annotations: vec![],
        })
    }

    #[test]
    fn flattens_nested_document() {
        let events = tree_to_events(&sample_tree());

        let expected = vec![
            Event::StartDocument,
            Event::StartHeading(2),
            Event::Inline(InlineContent::Text("Intro".to_string())),
            Event::StartContent,
            Event::StartParagraph,
            Event::Inline(InlineContent::Text("Welcome".to_string())),
            Event::EndParagraph,
            Event::EndContent,
            Event::EndHeading(2),
            Event::StartList {
                ordered: false,
                style: ListStyle::Bullet,
                form: ListForm::Short,
            },
            Event::StartListItem,
            Event::Inline(InlineContent::Text("Item".to_string())),
            Event::StartContent,
            Event::StartVerbatim {
                language: Some("rust".to_string()),
                subject: None,
                subject_href: None,
                parameters: Vec::new(),
            },
            Event::Inline(InlineContent::Text("fn main() {}".to_string())),
            Event::EndVerbatim,
            Event::EndContent,
            Event::EndListItem,
            Event::EndList,
            Event::StartDefinition,
            Event::StartDefinitionTerm,
            Event::Inline(InlineContent::Text("Term".to_string())),
            Event::EndDefinitionTerm,
            Event::StartDefinitionDescription,
            Event::StartContent,
            Event::StartParagraph,
            Event::Inline(InlineContent::Text("Definition".to_string())),
            Event::EndParagraph,
            Event::EndContent,
            Event::EndDefinitionDescription,
            Event::EndDefinition,
            // Post-refac/label cleanup: the bare-label metadata
            // path that used to emit a `lex-metadata:note` verbatim
            // is gone. The `:: note ::` annotation now flows through
            // the normal annotation events.
            Event::StartAnnotation {
                label: "note".to_string(),
                parameters: vec![("key".to_string(), "value".to_string())],
                form: LabelForm::Canonical,
            },
            Event::StartContent,
            Event::StartParagraph,
            Event::Inline(InlineContent::Text("Body".to_string())),
            Event::EndParagraph,
            Event::EndContent,
            Event::EndAnnotation {
                label: "note".to_string(),
            },
            Event::EndDocument,
        ];

        assert_eq!(events, expected);
    }

    #[test]
    fn round_trips_with_flat_to_nested() {
        let original = sample_tree();
        let events = tree_to_events(&original);
        let rebuilt = events_to_tree(&events).expect("failed to rebuild");

        assert_eq!(DocNode::Document(rebuilt), original);
    }

    /// Phase 3b (#614): `tree_to_events` no longer synthesizes a
    /// `frontmatter` annotation event from `document_annotations`.
    /// Format-specific serializers that need a packed YAML preamble
    /// read `document_annotations` from the IR directly. Lock the
    /// new contract so a future refactor doesn't accidentally
    /// reintroduce double-emission.
    #[test]
    fn document_annotations_do_not_synthesize_events() {
        use crate::ir::nodes::LabelForm;

        let doc = DocNode::Document(Document {
            title: None,
            subtitle: None,
            children: vec![DocNode::Paragraph(Paragraph {
                content: vec![InlineContent::Text("Body.".to_string())],
            })],
            document_annotations: vec![Annotation {
                label: "lex.metadata.author".to_string(),
                parameters: vec![],
                content: vec![DocNode::Paragraph(Paragraph {
                    content: vec![InlineContent::Text("Alice".to_string())],
                })],
                form: LabelForm::Canonical,
            }],
        });

        let events = tree_to_events(&doc);

        // No synthetic `frontmatter` annotation event is emitted.
        let has_frontmatter = events.iter().any(|e| {
            matches!(
                e,
                Event::StartAnnotation { label, .. } if label == "frontmatter"
            )
        });
        assert!(
            !has_frontmatter,
            "Phase 3b: tree_to_events must not synthesize a frontmatter event"
        );

        // The document body still produces its normal events.
        assert!(events.iter().any(|e| matches!(e, Event::StartParagraph)));
    }
}