inkmark 0.1.0

data/ext/inkmark/src/image.rs

@@ -0,0 +1,284 @@
+//! Image attribute injection filter and URL matcher.
+//!
+//! When enabled, replaces pulldown-cmark's default image event sequence
+//! (`Start(Tag::Image) ... End(TagEnd::Image)`) with a single `Event::Html`
+//! carrying a hand-built `<img>` tag that includes the "modern" loading and
+//! decoding hints:
+//!
+//! ```html
+//! <img src="..." alt="..." loading="lazy" decoding="async" />
+//! ```
+//!
+//! Pulldown-cmark's `Tag::Image` struct doesn't expose an "extra attributes"
+//! field, so rewriting the Tag in place isn't enough—we have to bypass
+//! the built-in image writer entirely and emit the HTML ourselves. Alt,
+//! title, and URL are escaped through the same `pulldown-cmark-escape`
+//! functions the upstream html writer uses, so the output stays byte-
+//! compatible with what pulldown-cmark would have produced plus the two
+//! extra attributes.
+
+use globset::GlobSet;
+use pulldown_cmark::{CowStr, Event, Tag, TagEnd};
+use pulldown_cmark_escape::{escape_href, escape_html};
+
+use crate::url_match::is_host_allowed;
+
+/// Rewrite every image in the event stream as a self-contained `Event::Html`
+/// carrying `<img ... loading="lazy" decoding="async">`.
+///
+/// We consume the input Vec to own each event, then rebuild with
+/// `Vec::with_capacity(events.len())` so passthrough events move by value
+/// and image events are replaced with a single Html event.
+pub fn add_lazy_loading(events: Vec<Event<'_>>) -> Vec<Event<'_>> {
+    let mut out: Vec<Event<'_>> = Vec::with_capacity(events.len());
+    let mut iter = events.into_iter();
+
+    while let Some(event) = iter.next() {
+        match event {
+            Event::Start(Tag::Image {
+                dest_url, title, ..
+            }) => {
+                // Consume events up to the matching End(Image), accumulating
+                // alt text from Text and Code payloads. Images can contain
+                // inline formatting (e.g. `![**bold**](img.png)`), which
+                // produces Start(Strong)/Text/End(Strong) events; the bare
+                // text content is what we want for the alt attribute.
+                let mut alt = String::new();
+                for inner in iter.by_ref() {
+                    match inner {
+                        Event::End(TagEnd::Image) => break,
+                        Event::Text(t) | Event::Code(t) => alt.push_str(&t),
+                        _ => {}
+                    }
+                }
+
+                let html = build_img_tag(&dest_url, &alt, &title);
+                out.push(Event::Html(CowStr::Boxed(html.into_boxed_str())));
+            }
+            other => out.push(other),
+        }
+    }
+
+    out
+}
+
+/// Drop images whose `src` host isn't in the allowlist. The whole
+/// `Start(Image) ... End(Image)` sequence is replaced with a single
+/// `Event::Text` carrying the image's alt text, or removed entirely
+/// when alt is empty. Non-web URLs pass through: [`is_host_allowed`]
+/// returns true for any URL with no parseable host.
+///
+/// Alt accumulation matches `add_lazy_loading`: images can contain
+/// markdown like `![**bold**](img.png)`, producing
+/// Start(Strong)/Text/End(Strong) events—we pull the raw text payloads
+/// out and discard formatting.
+pub fn filter_by_hosts<'a>(events: Vec<Event<'a>>, set: &GlobSet) -> Vec<Event<'a>> {
+    let mut out: Vec<Event<'a>> = Vec::with_capacity(events.len());
+    let mut iter = events.into_iter();
+
+    while let Some(event) = iter.next() {
+        match event {
+            Event::Start(Tag::Image { ref dest_url, .. }) if !is_host_allowed(dest_url, set) => {
+                let mut alt = String::new();
+                for inner in iter.by_ref() {
+                    match inner {
+                        Event::End(TagEnd::Image) => break,
+                        Event::Text(t) | Event::Code(t) => alt.push_str(&t),
+                        _ => {}
+                    }
+                }
+                if !alt.is_empty() {
+                    out.push(Event::Text(CowStr::Boxed(alt.into_boxed_str())));
+                }
+            }
+            other => out.push(other),
+        }
+    }
+
+    out
+}
+
+/// Construct the `<img>` HTML string with `loading="lazy"` and
+/// `decoding="async"` attributes. `src` is escaped as a URL (percent-
+/// encoded where necessary); `alt` and `title` are HTML-attribute
+/// escaped. The output matches pulldown-cmark's built-in image writer
+/// plus the two extra hint attributes.
+#[inline]
+fn build_img_tag(src: &str, alt: &str, title: &str) -> String {
+    // Rough capacity estimate: base tag (~60) + src + alt + title length.
+    let mut out = String::with_capacity(60 + src.len() + alt.len() + title.len());
+    out.push_str("<img src=\"");
+
+    // escape_href percent-encodes problematic bytes and also handles HTML
+    // specials (&, <, etc.). Matches pulldown-cmark's upstream behavior.
+    let _ = escape_href(&mut out, src);
+    out.push_str("\" alt=\"");
+    let _ = escape_html(&mut out, alt);
+    out.push('"');
+    if !title.is_empty() {
+        out.push_str(" title=\"");
+        let _ = escape_html(&mut out, title);
+        out.push('"');
+    }
+    out.push_str(" loading=\"lazy\" decoding=\"async\" />");
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{add_lazy_loading, build_img_tag, filter_by_hosts};
+    use globset::{Glob, GlobSetBuilder};
+    use pulldown_cmark::{CowStr, Event, LinkType, Tag, TagEnd};
+
+    fn host_set(patterns: &[&str]) -> globset::GlobSet {
+        let mut b = GlobSetBuilder::new();
+        for p in patterns {
+            b.add(Glob::new(p).unwrap());
+        }
+        b.build().unwrap()
+    }
+
+    #[test]
+    fn basic_tag() {
+        let html = build_img_tag("img.png", "a picture", "");
+        assert_eq!(
+            html,
+            r#"<img src="img.png" alt="a picture" loading="lazy" decoding="async" />"#
+        );
+    }
+
+    #[test]
+    fn with_title() {
+        let html = build_img_tag("img.png", "alt", "the title");
+        assert_eq!(
+            html,
+            r#"<img src="img.png" alt="alt" title="the title" loading="lazy" decoding="async" />"#
+        );
+    }
+
+    #[test]
+    fn escapes_alt_html_specials() {
+        // Attempted HTML injection in alt—must come out escaped.
+        let html = build_img_tag("img.png", "a\"b<c>d&e", "");
+        assert!(html.contains("alt=\"a&quot;b&lt;c&gt;d&amp;e\""));
+    }
+
+    #[test]
+    fn escapes_url_ampersand() {
+        let html = build_img_tag("img.png?a=1&b=2", "alt", "");
+        // pulldown-cmark-escape writes `&` as `&amp;` in hrefs.
+        assert!(html.contains("src=\"img.png?a=1&amp;b=2\""));
+    }
+
+    #[test]
+    fn empty_alt_still_valid() {
+        let html = build_img_tag("img.png", "", "");
+        assert_eq!(
+            html,
+            r#"<img src="img.png" alt="" loading="lazy" decoding="async" />"#
+        );
+    }
+
+    #[test]
+    fn title_skipped_when_empty() {
+        let html = build_img_tag("img.png", "alt", "");
+        assert!(!html.contains("title="));
+    }
+
+    #[test]
+    fn add_lazy_loading_collapses_image_events_into_html() {
+        // Start(Image) + Text("alt") + End(Image) → single Html event with loading=
+        let events = vec![
+            Event::Start(Tag::Image {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("photo.jpg"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("alt text")),
+            Event::End(TagEnd::Image),
+        ];
+        let out = add_lazy_loading(events);
+        assert_eq!(out.len(), 1, "should collapse to one event");
+        match &out[0] {
+            Event::Html(html) => {
+                assert!(
+                    html.contains("loading="),
+                    "missing loading attribute: {html}"
+                );
+                assert!(html.contains("alt=\"alt text\""), "missing alt: {html}");
+                assert!(html.contains("src=\"photo.jpg\""), "missing src: {html}");
+            }
+            other => panic!("expected Html event, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn filter_by_hosts_drops_disallowed_image_to_alt_text() {
+        let events = vec![
+            Event::Start(Tag::Image {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("https://evil.com/bad.png"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("fallback alt")),
+            Event::End(TagEnd::Image),
+        ];
+        let out = filter_by_hosts(events, &host_set(&["example.net"]));
+        assert_eq!(out.len(), 1);
+        match &out[0] {
+            Event::Text(t) => assert_eq!(t.as_ref(), "fallback alt"),
+            other => panic!("expected Text event, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn filter_by_hosts_drops_disallowed_image_with_empty_alt_entirely() {
+        let events = vec![
+            Event::Start(Tag::Image {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("https://evil.com/x.png"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::End(TagEnd::Image),
+        ];
+        let out = filter_by_hosts(events, &host_set(&["example.net"]));
+        assert!(out.is_empty(), "expected zero events, got {out:?}");
+    }
+
+    #[test]
+    fn filter_by_hosts_keeps_allowed_images_untouched() {
+        let events = vec![
+            Event::Start(Tag::Image {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("https://cdn.example.net/ok.png"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("alt")),
+            Event::End(TagEnd::Image),
+        ];
+        let out = filter_by_hosts(events, &host_set(&["*.example.net"]));
+        assert_eq!(out.len(), 3);
+        assert!(matches!(out[0], Event::Start(Tag::Image { .. })));
+    }
+
+    #[test]
+    fn filter_by_hosts_leaves_relative_images_alone() {
+        let events = vec![
+            Event::Start(Tag::Image {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("/local/pic.png"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("alt")),
+            Event::End(TagEnd::Image),
+        ];
+        let out = filter_by_hosts(events, &host_set(&[]));
+        assert_eq!(out.len(), 3);
+        assert!(matches!(out[0], Event::Start(Tag::Image { .. })));
+    }
+}

data/ext/inkmark/src/lib.rs

@@ -0,0 +1,54 @@
+#![forbid(unsafe_code)]
+
+use magnus::{function, prelude::*, Error, Ruby};
+
+mod autolink;
+mod chunks_by_heading;
+mod chunks_by_size;
+mod document;
+mod emoji;
+mod handler;
+mod heading;
+mod highlight;
+mod image;
+mod link;
+mod options;
+mod plain_text;
+mod scheme_filter;
+mod stats;
+mod tag_filter;
+mod toc;
+mod truncate;
+mod url_match;
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let inkmark = ruby.define_class("Inkmark", ruby.class_object())?;
+    inkmark.define_singleton_method("_native_to_html", function!(document::native_to_html, 2))?;
+    inkmark.define_singleton_method("_native_to_markdown", function!(document::native_to_markdown, 2))?;
+    inkmark.define_singleton_method("_native_to_plain_text", function!(document::native_to_plain_text, 2))?;
+    inkmark.define_singleton_method(
+        "_native_chunks_by_heading",
+        function!(chunks_by_heading::native_chunks_by_heading, 2),
+    )?;
+    inkmark.define_singleton_method(
+        "_native_chunks_by_size",
+        function!(chunks_by_size::native_chunks_by_size, 2),
+    )?;
+    inkmark.define_singleton_method(
+        "_native_truncate_markdown",
+        function!(truncate::native_truncate_markdown, 3),
+    )?;
+    inkmark.define_singleton_method(
+        "_native_render_full",
+        function!(document::native_render_full, 2),
+    )?;
+    inkmark.define_singleton_method("_syntax_css", function!(highlight::syntax_css, 1))?;
+    inkmark.define_singleton_method("_syntax_themes", function!(highlight::syntax_themes, 0))?;
+    inkmark.define_singleton_method("_native_walk", function!(handler::native_walk, 3))?;
+    inkmark.define_singleton_method(
+        "_native_render_with_handlers",
+        function!(handler::native_render_with_handlers, 3),
+    )?;
+    Ok(())
+}

data/ext/inkmark/src/link.rs

@@ -0,0 +1,291 @@
+//! External link `rel` attribute injection filter and URL matcher.
+//!
+//! When enabled, replaces the `Start(Tag::Link)` and matching
+//! `End(TagEnd::Link)` events for every external link with hand-built
+//! `<a href="..." rel="nofollow noopener">` / `</a>` HTML events. Inner
+//! events (text, emphasis, inline code, images) pass through unchanged,
+//! so pulldown-cmark's built-in writers still render the link content:
+//! we only replace the opening and closing tags.
+//!
+//! "External" here means the URL starts with `http://` or `https://`
+//! (case-insensitive). Relative paths, anchor fragments, and non-web
+//! schemes (`mailto:`, `tel:`, `javascript:`) are not touched:
+
+use globset::GlobSet;
+use pulldown_cmark::{CowStr, Event, Tag, TagEnd};
+use pulldown_cmark_escape::{escape_href, escape_html};
+
+use crate::url_match::is_host_allowed;
+
+/// Add `rel="nofollow noopener"` to every external `<a>` tag by replacing
+/// its `Start(Link)` event with a synthesized `Event::Html` opening tag
+/// and its matching `End(Link)` event with a `</a>` close tag.
+pub fn add_nofollow(events: Vec<Event<'_>>) -> Vec<Event<'_>> {
+    let mut out: Vec<Event<'_>> = Vec::with_capacity(events.len());
+    let mut iter = events.into_iter();
+
+    while let Some(event) = iter.next() {
+        match event {
+            Event::Start(Tag::Link {
+                link_type: _,
+                ref dest_url,
+                ref title,
+                id: _,
+            }) if is_external(dest_url) => {
+                let open = build_link_open(dest_url, title);
+                out.push(Event::Html(CowStr::Boxed(open.into_boxed_str())));
+
+                // Consume inner events through the matching End(Link),
+                // depth-counting so a nested link doesn't break the
+                // close-tag pairing. CommonMark disallows nested links
+                // in valid markdown, so depth should always reach zero on
+                // the first End we see.
+                let mut depth: usize = 1;
+                for inner in iter.by_ref() {
+                    let is_link_start = matches!(&inner, Event::Start(Tag::Link { .. }));
+                    let is_link_end = matches!(&inner, Event::End(TagEnd::Link));
+
+                    if is_link_start {
+                        depth += 1;
+                        out.push(inner);
+                    } else if is_link_end {
+                        depth -= 1;
+                        if depth == 0 {
+                            out.push(Event::Html(CowStr::Borrowed("</a>")));
+                            break;
+                        }
+                        out.push(inner);
+                    } else {
+                        out.push(inner);
+                    }
+                }
+            }
+            other => out.push(other),
+        }
+    }
+
+    out
+}
+
+/// Drop `<a>` tags whose destination URL's host isn't in the allowlist,
+/// leaving the inner content (text, emphasis, images) in place as a
+/// bare phrase. Non-web URLs (relative paths, `mailto:`, etc.) pass
+/// through.
+pub fn filter_by_hosts<'a>(events: Vec<Event<'a>>, set: &GlobSet) -> Vec<Event<'a>> {
+    let mut out: Vec<Event<'a>> = Vec::with_capacity(events.len());
+    let mut iter = events.into_iter();
+
+    while let Some(event) = iter.next() {
+        match event {
+            Event::Start(Tag::Link { ref dest_url, .. }) if !is_host_allowed(dest_url, set) => {
+                let mut depth: usize = 1;
+                for inner in iter.by_ref() {
+                    match &inner {
+                        Event::Start(Tag::Link { .. }) => {
+                            depth += 1;
+                            out.push(inner);
+                        }
+                        Event::End(TagEnd::Link) => {
+                            depth -= 1;
+                            if depth == 0 {
+                                break;
+                            }
+                            out.push(inner);
+                        }
+                        _ => out.push(inner),
+                    }
+                }
+            }
+            other => out.push(other),
+        }
+    }
+
+    out
+}
+
+/// Return true when the URL starts with `http://` or `https://` (case
+/// insensitive). Relative paths, anchor fragments, and `mailto:` /
+/// `tel:` / `javascript:` URLs return false.
+#[inline]
+fn is_external(url: &str) -> bool {
+    url.split_once("://").is_some_and(|(scheme, _)| {
+        scheme.eq_ignore_ascii_case("http") || scheme.eq_ignore_ascii_case("https")
+    })
+}
+
+/// Construct the `<a href="..." title="..." rel="nofollow noopener">`
+/// opening tag. The URL goes through `escape_href` (percent-encoding +
+/// HTML-special escaping, matching pulldown-cmark's upstream behavior),
+/// and the title through `escape_html` for attribute context.
+#[inline]
+fn build_link_open(href: &str, title: &str) -> String {
+    let mut out = String::with_capacity(40 + href.len() + title.len());
+    out.push_str("<a href=\"");
+    let _ = escape_href(&mut out, href);
+    out.push('"');
+    if !title.is_empty() {
+        out.push_str(" title=\"");
+        let _ = escape_html(&mut out, title);
+        out.push('"');
+    }
+    out.push_str(" rel=\"nofollow noopener\">");
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{add_nofollow, build_link_open, filter_by_hosts, is_external};
+    use globset::{Glob, GlobSetBuilder};
+    use pulldown_cmark::{CowStr, Event, LinkType, Tag, TagEnd};
+
+    fn host_set(patterns: &[&str]) -> globset::GlobSet {
+        let mut b = GlobSetBuilder::new();
+        for p in patterns {
+            b.add(Glob::new(p).unwrap());
+        }
+        b.build().unwrap()
+    }
+
+    #[test]
+    fn external_detection() {
+        assert!(is_external("http://example.net"));
+        assert!(is_external("https://example.net"));
+        assert!(is_external("HTTPS://EXAMPLE.NET"));
+        assert!(is_external("Http://mixed.case"));
+
+        assert!(!is_external("/local/path"));
+        assert!(!is_external("relative.html"));
+        assert!(!is_external("#anchor"));
+        assert!(!is_external("mailto:user@example.net"));
+        assert!(!is_external("tel:+1234567890"));
+        assert!(!is_external("javascript:alert(1)"));
+        assert!(!is_external("//protocol-relative.com"));
+        assert!(!is_external(""));
+        assert!(!is_external("h"));
+        assert!(!is_external("http"));
+        assert!(!is_external("https"));
+    }
+
+    #[test]
+    fn open_tag_basic() {
+        assert_eq!(
+            build_link_open("https://example.net", ""),
+            r#"<a href="https://example.net" rel="nofollow noopener">"#
+        );
+    }
+
+    #[test]
+    fn open_tag_with_title() {
+        assert_eq!(
+            build_link_open("https://example.net", "the title"),
+            r#"<a href="https://example.net" title="the title" rel="nofollow noopener">"#
+        );
+    }
+
+    #[test]
+    fn open_tag_escapes_url_ampersand() {
+        let tag = build_link_open("https://example.net/?a=1&b=2", "");
+        assert!(tag.contains(r#"href="https://example.net/?a=1&amp;b=2""#));
+    }
+
+    #[test]
+    fn open_tag_escapes_title_specials() {
+        let tag = build_link_open("https://example.net", r#"a "quoted" <title>"#);
+        assert!(tag.contains("&quot;quoted&quot;"));
+        assert!(tag.contains("&lt;title&gt;"));
+    }
+
+    #[test]
+    fn add_nofollow_adds_rel_to_external_link() {
+        // Start(Link) + Text("click") + End(Link) → Html open + Text + Html close
+        let events = vec![
+            Event::Start(Tag::Link {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("https://example.net"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("click")),
+            Event::End(TagEnd::Link),
+        ];
+        let out = add_nofollow(events);
+        // Should produce: Html(open), Text("click"), Html("</a>")
+        assert_eq!(out.len(), 3, "expected 3 events, got {}", out.len());
+        match &out[0] {
+            Event::Html(html) => {
+                assert!(
+                    html.contains("nofollow"),
+                    "opening tag must contain nofollow: {html}"
+                );
+                assert!(
+                    html.contains("https://example.net"),
+                    "opening tag must contain href: {html}"
+                );
+            }
+            other => panic!("expected Html open event, got {other:?}"),
+        }
+        match &out[2] {
+            Event::Html(html) => assert_eq!(html.as_ref(), "</a>"),
+            other => panic!("expected Html close event, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn filter_by_hosts_drops_disallowed_link_tags_keeping_text() {
+        // Start(Link to evil) + Text("click") + End(Link) →
+        // just Text("click"), with the link wrapper gone.
+        let events = vec![
+            Event::Start(Tag::Link {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("https://evil.com"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("click me")),
+            Event::End(TagEnd::Link),
+        ];
+        let out = filter_by_hosts(events, &host_set(&["example.net"]));
+        assert_eq!(out.len(), 1);
+        match &out[0] {
+            Event::Text(t) => assert_eq!(t.as_ref(), "click me"),
+            other => panic!("expected Text, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn filter_by_hosts_keeps_allowed_links_untouched() {
+        let events = vec![
+            Event::Start(Tag::Link {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("https://cdn.example.net/doc"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("ok")),
+            Event::End(TagEnd::Link),
+        ];
+        let out = filter_by_hosts(events, &host_set(&["*.example.net"]));
+        assert_eq!(out.len(), 3);
+        assert!(matches!(out[0], Event::Start(Tag::Link { .. })));
+        assert!(matches!(out[2], Event::End(TagEnd::Link)));
+    }
+
+    #[test]
+    fn filter_by_hosts_leaves_relative_and_mailto_alone() {
+        // Even with an empty allowlist that blocks everything external,
+        // relative/mailto links pass through unchanged.
+        let events = vec![
+            Event::Start(Tag::Link {
+                link_type: LinkType::Inline,
+                dest_url: CowStr::Borrowed("/local"),
+                title: CowStr::Borrowed(""),
+                id: CowStr::Borrowed(""),
+            }),
+            Event::Text(CowStr::Borrowed("home")),
+            Event::End(TagEnd::Link),
+        ];
+        let out = filter_by_hosts(events, &host_set(&[]));
+        assert_eq!(out.len(), 3);
+        assert!(matches!(out[0], Event::Start(Tag::Link { .. })));
+    }
+}