mini-cite 0.2.0

BibTeX-backed inline citations and footnotes for the mini-* family.
Documentation
use mini_cite::{process, Bibliography, CiteError, CiteStyle};

/// A bibliography defining `smith2020` and `doe2019`.
fn bibliography() -> Bibliography {
    let source = r#"
@article{smith2020,
  author = {Jane Smith},
  title = {On Small Things},
  journal = {Journal of Minimal Systems},
  year = {2020}
}

@book{doe2019,
  author = {John Doe},
  title = {Larger Things},
  publisher = {Minimal Press},
  year = {2019}
}
"#;
    Bibliography::from_entries(mini_cite::parse_entries(source).expect("fixture should parse"))
}

/// Processes against the fixture bibliography in the default style, asserting success.
fn processed(body: &str) -> String {
    process(body, &bibliography(), &CiteStyle::default()).expect("body should process")
}

#[test]
fn rewrites_citation_and_appends_matching_footnote() {
    let body = "Small things matter [@smith2020].";

    let out = processed(body);

    assert!(
        out.starts_with(
            r##"Small things matter <sup id="fnref-1" class="footnote-ref"><a href="#fn-1">1</a></sup>."##
        ),
        "inline reference missing or malformed: {out}"
    );
    assert!(
        out.contains(r##"<li id="fn-1" class="footnote">Jane Smith. On Small Things. Journal of Minimal Systems. 2020. <a href="#fnref-1" class="footnote-back">↩</a></li>"##),
        "footnote item missing or malformed: {out}"
    );
}

#[test]
fn footnote_block_is_separated_from_the_body_by_a_blank_line() {
    let out = processed("Cited [@smith2020].");

    let block_start = out.find("<hr").expect("footnote block should be present");
    assert!(
        out[..block_start].ends_with("\n\n"),
        "footnote block must follow a blank line or CommonMark folds it into the last paragraph: {out}"
    );
}

#[test]
fn footnote_block_comes_after_all_prose() {
    let body = "First [@smith2020].\n\nSecond paragraph [@doe2019].";

    let out = processed(body);

    let block_start = out.find("<hr").expect("footnote block should be present");
    let last_prose = out.find("Second paragraph").expect("prose should survive");
    assert!(block_start > last_prose, "footnote block is not last: {out}");
}

#[test]
fn footnotes_appear_in_first_appearance_order() {
    let body = "Later work [@doe2019] built on earlier work [@smith2020].";

    let out = processed(body);

    let first = out.find("John Doe").expect("doe2019 should render");
    let second = out.find("Jane Smith").expect("smith2020 should render");
    assert!(first < second, "footnotes are not in citation order: {out}");
    assert!(out.contains(r##"<li id="fn-1" class="footnote">John Doe."##));
    assert!(out.contains(r##"<li id="fn-2" class="footnote">Jane Smith."##));
}

#[test]
fn repeated_citation_produces_one_footnote() {
    let body = "Here [@smith2020] and again [@smith2020].";

    let out = processed(body);

    assert_eq!(out.matches("<li id=").count(), 1, "expected one footnote: {out}");
    assert_eq!(out.matches("Jane Smith").count(), 1);
}

#[test]
fn body_without_citations_round_trips_byte_identical() {
    let body = "# Title\n\nProse with [a link](other.md), `[@incode]`, and [brackets].\n";

    let out = processed(body);

    assert_eq!(out, body);
}

#[test]
fn body_without_citations_gains_no_trailing_separator() {
    let out = processed("Just prose.");

    assert_eq!(out, "Just prose.");
    assert!(!out.contains("<hr"));
}

#[test]
fn citations_in_code_produce_no_footnote_block() {
    let body = "Write it like this:\n\n```markdown\nSee [@smith2020].\n```\n";

    let out = processed(body);

    assert_eq!(out, body);
}

#[test]
fn unknown_citation_key_is_an_error_naming_the_key() {
    let error = process("Cite [@nosuchkey].", &bibliography(), &CiteStyle::default())
        .expect_err("unknown key should not process");

    let CiteError::UnknownCitation { key } = &error else {
        panic!("expected UnknownCitation, got: {error}");
    };
    assert_eq!(key, "nosuchkey");
    assert!(error.to_string().contains("nosuchkey"));
}

#[test]
fn emitted_markup_uses_only_sanitizer_safe_elements() {
    let body = "Both [@smith2020;doe2019] agree.";

    let out = processed(body);

    // mini-docs cleans rendered HTML with ammonia's default policy plus a generic
    // `id` and `class`. Anything outside this set would be silently stripped
    // downstream.
    let allowed = ["sup", "a", "hr", "ol", "li"];
    for tag in out.split('<').skip(1) {
        let name = tag
            .trim_start_matches('/')
            .split(['>', ' '])
            .next()
            .unwrap_or_default();
        if name.is_empty() {
            continue;
        }
        assert!(
            allowed.contains(&name),
            "emitted <{name}> is outside the sanitizer-safe set: {out}"
        );
    }
}

#[test]
fn a_custom_style_names_every_emitted_class() {
    let style = CiteStyle::default()
        .reference_class("c-ref")
        .separator_class("c-sep")
        .list_class("c-list")
        .item_class("c-item")
        .backlink_class("c-back");

    let out = process("Cited [@smith2020].", &bibliography(), &style)
        .expect("body should process");

    for expected in [
        r##"<sup id="fnref-1" class="c-ref">"##,
        r##"<hr class="c-sep">"##,
        r##"<ol class="c-list">"##,
        r##"<li id="fn-1" class="c-item">"##,
        r##"<a href="#fnref-1" class="c-back">"##,
    ] {
        assert!(out.contains(expected), "missing {expected} in: {out}");
    }

    for default in ["footnote-ref", "footnotes-sep", "footnotes", "footnote-back"] {
        assert!(
            !out.contains(default),
            "default class {default} survived a custom style: {out}"
        );
    }
}

#[test]
fn a_custom_backlink_label_replaces_the_default_glyph() {
    let style = CiteStyle::default().backlink_label("back to text");

    let out = process("Cited [@smith2020].", &bibliography(), &style)
        .expect("body should process");

    assert!(out.contains(r##"<a href="#fnref-1" class="footnote-back">back to text</a>"##));
    assert!(!out.contains('↩'), "default glyph survived a custom label: {out}");
}

#[test]
fn emptying_every_class_emits_markup_with_no_class_attribute() {
    let style = CiteStyle::default()
        .reference_class("")
        .separator_class("")
        .list_class("")
        .item_class("")
        .backlink_class("");

    let out = process("Cited [@smith2020].", &bibliography(), &style)
        .expect("body should process");

    assert!(!out.contains("class="), "unexpected class attribute: {out}");
    // The structural hooks the ids provide must survive dropping the classes — they
    // are what a class-free stylesheet selects on.
    assert!(out.contains(r##"<sup id="fnref-1">"##));
    assert!(out.contains(r##"<li id="fn-1">"##));
    assert!(out.contains("<hr>\n<ol>\n"));
}

#[test]
fn styling_changes_nothing_about_numbering_or_linkage() {
    let body = "One [@smith2020], two [@doe2019], one again [@smith2020].";
    let styled = CiteStyle::default().reference_class("x").item_class("");

    let plain_out = processed(body);
    let styled_out = process(body, &bibliography(), &styled).expect("body should process");

    // Strip every class attribute from both and the documents must be identical:
    // style names elements, it never moves or renumbers them.
    assert_eq!(strip_classes(&plain_out), strip_classes(&styled_out));
}

/// Removes every ` class="…"` attribute from `html`.
fn strip_classes(html: &str) -> String {
    let mut out = String::with_capacity(html.len());
    let mut rest = html;

    while let Some(start) = rest.find(r#" class=""#) {
        out.push_str(&rest[..start]);
        let after = &rest[start + r#" class=""#.len()..];
        let close = after.find('"').expect("class attribute should be closed");
        rest = &after[close + 1..];
    }
    out.push_str(rest);

    out
}