madfun/

lib.rs

//! # `madfun`
//!
//! **WARNING**: This crate is incomplete, and does not include full support for
//! all Markdown blocks. Known working Markdown primitives:
//!
//! * code
//! * inlinecode
//! * links
//! * paragraphs
//! * text
//!
//! <hr/>
//!
//! Would you like to use `Ma`rkdown to post `A`tlassian `D`ocument `F`ormatted
//! content while still having `fun`? Then this tool's for you!
//!
//! ## How It Works
//!
//! `madfun` works by taking input in
//! [Markdown](https://www.markdownguide.org/), either as text or a parsed
//! abstract syntax tree
//! ([AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)) and converting
//! it to an `adf:Node` tree that conforms to Atlassian's
//! [ADF](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
//! This type implements serde's `Serialize` and `Deserialize` traits, so it's
//! easy to convert to a JSON representation via `serde_json`.
//!
//! Once you've got that, it should be simple (lol) to use any HTTP or Atlassian
//! client to send it wherever it's going.
//!
//! ## Usage
//!
//! The core of `madfun` is the [`ToAdf`] trait; this exposes methods for
//! converting text or pre-parsed Markdown (via the `markdown` crate) into a
//! `serde_json::Value` that can then be serialized as you desire.
//!
//! If you have Markdown text:
//!
//! ```
//! let adf = madfun::from_str(
//!     "Here is my Markdown content",
//! ).unwrap();
//! ```
//!
//! If you've already got the Markdown parsed into a `markdown::mdast::Node`,
//! then you can use the infallible [`ToAdf::to_adf`] method:
//!
//! ```
//! use madfun::ToAdf;
//!
//! let mdast = markdown::to_mdast(
//!     "Here is my Markdown content",
//!     &markdown::ParseOptions::default(),
//! ).unwrap();
//!
//! let adf = mdast.to_adf();
//! ```
//!
//! ## Limitations
//!
//! `madfun` is currently unidirectional; it takes Markdown and renders ADF
//! JSON. Unfortunately, it can't (yet?) take ADF as returned from the Atlassian
//! APIs and convert it back to Markdown, though in theory this should be doable
//! (if not actually isomorphic).
//!
//! ## LICENSE
//!
//! `madfun` is dual-licensed as MIT or Apache-2.0. Have fun.

pub mod adf;

use adf::{Mark, Node, mark::LinkAttrs, node::CodeBlockAttrs};
use markdown::{
    mdast::{self, Code, InlineCode, Link, Paragraph, Root, Text},
    message::Message,
};
use std::fmt::Display;

pub use markdown::ParseOptions;

#[derive(Debug)]
pub enum Error {
    Markdown(Message),
}

impl Display for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Error::Markdown(message) => write!(f, "{message}"),
        }
    }
}

impl std::error::Error for Error {}

impl From<Message> for Error {
    fn from(value: Message) -> Self {
        Self::Markdown(value)
    }
}

/// Generate ADF from Markdown text.
///
/// # Errors
///
/// Returns an error if the Markdown is invalid.
pub fn from_str<T: AsRef<str>>(markdown: T) -> Result<Node, Error> {
    Ok(
        markdown::to_mdast(markdown.as_ref(), &ParseOptions::default())?
            .to_adf(),
    )
}

pub trait ToAdf {
    /// Generate ADF from a pre-parsed `markdown::Node`.
    fn to_adf(&self) -> Node;
}

impl ToAdf for mdast::Node {
    fn to_adf(&self) -> Node {
        to_adf(self)
    }
}

fn to_adf(node: &mdast::Node) -> Node {
    match node {
        mdast::Node::Root(Root {
            children,
            ..
        }) => Node::Doc {
            content: children.iter().map(to_adf).collect(),
            version: 1,
        },
        mdast::Node::Blockquote(blockquote) => todo!(),
        mdast::Node::Break(_) => todo!(),
        mdast::Node::Code(Code {
            value,
            lang,
            ..
        }) => Node::codeblock()
            .and_attrs(
                lang.as_ref()
                    .map(|l| CodeBlockAttrs::builder().language(l).build()),
            )
            .content_entry(Node::text().text(value).build())
            .build(),
        mdast::Node::Definition(definition) => todo!(),
        mdast::Node::Delete(delete) => todo!(),
        mdast::Node::Emphasis(emphasis) => todo!(),
        mdast::Node::FootnoteDefinition(footnote_definition) => todo!(),
        mdast::Node::FootnoteReference(footnote_reference) => todo!(),
        mdast::Node::Heading(heading) => todo!(),
        mdast::Node::Html(html) => todo!(),
        mdast::Node::Image(image) => todo!(),
        mdast::Node::ImageReference(image_reference) => todo!(),
        mdast::Node::InlineCode(InlineCode {
            value,
            ..
        }) => Node::Text {
            text: value.to_string(),
            marks: vec![Mark::Code],
        },
        mdast::Node::InlineMath(inline_math) => todo!(),
        mdast::Node::Link(Link {
            url,
            children,
            title,
            ..
        }) => {
            let Some(mdast::Node::Text(Text {
                value,
                ..
            })) = children.first()
            else {
                // TODO: Don't panic (grab your towel).
                panic!("missing text on link");
            };

            Node::Text {
                text: value.to_string(),
                marks: vec![Mark::Link {
                    attrs: LinkAttrs::builder()
                        .href(url)
                        .and_title(title.as_ref())
                        .build(),
                }],
            }
        },
        mdast::Node::LinkReference(link_reference) => todo!(),
        mdast::Node::List(list) => todo!(),
        mdast::Node::ListItem(list_item) => todo!(),
        mdast::Node::Math(math) => todo!(),
        mdast::Node::MdxFlowExpression(mdx_flow_expression) => todo!(),
        mdast::Node::MdxJsxFlowElement(mdx_jsx_flow_element) => todo!(),
        mdast::Node::MdxJsxTextElement(mdx_jsx_text_element) => todo!(),
        mdast::Node::MdxTextExpression(mdx_text_expression) => todo!(),
        mdast::Node::MdxjsEsm(mdxjs_esm) => todo!(),
        mdast::Node::Paragraph(Paragraph {
            children,
            ..
        }) => Node::paragraph()
            .content(children.iter().map(to_adf).collect())
            .build(),
        mdast::Node::Strong(strong) => todo!(),
        mdast::Node::Table(table) => todo!(),
        mdast::Node::TableCell(table_cell) => todo!(),
        mdast::Node::TableRow(table_row) => todo!(),
        mdast::Node::Text(Text {
            value,
            ..
        }) => Node::text().text(value).build(),
        mdast::Node::ThematicBreak(thematic_break) => todo!(),
        mdast::Node::Toml(toml) => todo!(),
        mdast::Node::Yaml(yaml) => todo!(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use markdown::mdast::Node;
    use serde_json::json;

    mod to_adf {
        use super::*;
        use markdown::{ParseOptions, mdast::Root};
        use pretty_assertions::assert_eq;

        #[test]
        fn test_empty_root() {
            assert_eq!(
                serde_json::to_value(
                    Node::Root(Root {
                        children: vec![],
                        position: None,
                    })
                    .to_adf()
                )
                .unwrap(),
                json!({
                    "content": [],
                    "type": "doc",
                    "version": 1,
                }),
            );
        }

        #[test]
        fn test_paragraph() {
            let node = markdown::to_mdast(
                "This is a paragraph.",
                &ParseOptions::default(),
            )
            .unwrap();
            assert_eq!(
                serde_json::to_value(node.to_adf()).unwrap(),
                json!({
                    "content": [{
                        "content": [{
                            "text": "This is a paragraph.",
                            "type": "text",
                        }],
                        "type": "paragraph",
                    }],
                    "type": "doc",
                    "version": 1,
                }),
                "{node:#?}",
            );

            let node = serde_json::to_value(
                markdown::to_mdast("", &ParseOptions::default())
                    .unwrap()
                    .to_adf(),
            )
            .unwrap();
            assert_eq!(
                node,
                json!({
                    "content": [],
                    "type": "doc",
                    "version": 1,
                }),
                "{:#?}",
                node,
            );
        }

        #[test]
        fn test_multiline_paragraph() {
            let node = serde_json::to_value(
                markdown::to_mdast(
                    "This is a\nmultiline paragraph.",
                    &ParseOptions::default(),
                )
                .unwrap()
                .to_adf(),
            )
            .unwrap();
            assert_eq!(
                node,
                json!({
                    "content": [{
                        "content": [{
                            "text": "This is a\nmultiline paragraph.",
                            "type": "text",
                        }],
                        "type": "paragraph",
                    }],
                    "type": "doc",
                    "version": 1,
                }),
                "{node:#?}",
            );
        }

        #[test]
        fn test_multi_paragraph() {
            let node = serde_json::to_value(
                markdown::to_mdast(
                    "This is a paragraph.\n\nAnd another one.",
                    &ParseOptions::default(),
                )
                .unwrap()
                .to_adf(),
            )
            .unwrap();
            assert_eq!(
                node,
                json!({
                    "content": [{
                        "content": [{
                            "text": "This is a paragraph.",
                            "type": "text",
                        }],
                        "type": "paragraph",
                    },{
                        "content": [{
                            "text": "And another one.",
                            "type": "text",
                        }],
                        "type": "paragraph",
                    }],
                    "type": "doc",
                    "version": 1,
                }),
                "{node:#?}",
            );
        }

        #[test]
        fn test_link() {
            let node = serde_json::to_value(
                markdown::to_mdast(
                    "This is a paragraph [with](https://example.com).",
                    &ParseOptions::default(),
                )
                .unwrap()
                .to_adf(),
            )
            .unwrap();
            assert_eq!(
                node,
                json!({
                    "content": [{
                        "content": [{
                            "text": "This is a paragraph ",
                            "type": "text",
                        },{
                            "text": "with",
                            "type": "text",
                            "marks": [{
                                "attrs": {
                                    "href": "https://example.com",
                                },
                                "type": "link",
                            }],
                        },{
                            "text": ".",
                            "type": "text",
                        }],
                        "type": "paragraph",
                    }],
                    "type": "doc",
                    "version": 1,
                }),
                "{node:#?}",
            );
        }

        #[test]
        fn test_link_with_title() {
            let node = serde_json::to_value(markdown::to_mdast(
                r#"This is a paragraph [with](https://example.com "my title")."#,
                &ParseOptions::default(),
            )
            .unwrap().to_adf()).unwrap();
            assert_eq!(
                node,
                json!({
                    "content": [{
                        "content": [{
                            "text": "This is a paragraph ",
                            "type": "text",
                        },{
                            "text": "with",
                            "type": "text",
                            "marks": [{
                                "attrs": {
                                    "href": "https://example.com",
                                    "title": "my title",
                                },
                                "type": "link",
                            }],
                        },{
                            "text": ".",
                            "type": "text",
                        }],
                        "type": "paragraph",
                    }],
                    "type": "doc",
                    "version": 1,
                }),
                "{node:#?}",
            );
        }

        #[test]
        fn test_inline_code() {
            let node = serde_json::to_value(
                markdown::to_mdast(
                    "inline `codehighlight` block",
                    &ParseOptions::default(),
                )
                .unwrap()
                .to_adf(),
            )
            .unwrap();
            assert_eq!(
                node,
                json!({
                    "content": [{
                        "content": [{
                            "text": "inline ",
                            "type": "text",
                        },{
                            "type": "text",
                            "text": "codehighlight",
                            "marks": [{
                                "type": "code",
                            }],
                        },{
                            "text": " block",
                            "type": "text",
                        }],
                        "type": "paragraph",
                    }],
                    "type": "doc",
                    "version": 1,
                }),
                "{node:#?}",
            );
        }
    }
}