lore_engine/engine/

link_parser.rs

//! Wiki link parsing, slug generation, and link rewriting.
//!
//! Handles `[[Page Name]]` and `[[Page Name|alias]]` syntax. Uses
//! pulldown-cmark to correctly identify code blocks and inline code spans,
//! so links inside code are reliably ignored.

use pulldown_cmark::{Event, Options, Parser, Tag};
use regex::Regex;
use serde::Serialize;
use std::sync::LazyLock;

static WIKILINK_RE: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"\[\[([^\[\]]+)\]\]").expect("Invalid wikilink regex"));

/// A parsed `[[wikilink]]` extracted from markdown content.
#[derive(Debug, Serialize, Clone, PartialEq, Eq)]
pub struct WikiLink {
    /// Original target text as written (e.g. `"Page Name"`).
    pub target: String,
    /// Alias text if present (`[[target|alias]]`).
    pub alias: Option<String>,
    /// Normalized slug derived from target (e.g. `"page-name"`).
    pub slug: String,
    /// 1-based line number where this link appears.
    pub line_number: usize,
}

/// Normalize a page name into a slug.
///
/// Rules:
/// - Lowercase
/// - Trim whitespace
/// - Split on `/` and normalize each segment independently
/// - Within each segment: replace spaces and underscores with hyphens,
///   strip punctuation, collapse consecutive hyphens, trim leading/trailing hyphens
/// - Preserve Unicode alphanumeric characters
/// - Drop empty segments (handles `//`, leading `/`, trailing `/`)
/// - Rejoin with `/`
pub fn slugify(name: &str) -> String {
    let trimmed = name.trim().to_lowercase();

    let segments: Vec<String> = trimmed
        .split('/')
        .filter_map(|segment| {
            let normalized = slugify_segment(segment);
            if normalized.is_empty() { None } else { Some(normalized) }
        })
        .collect();

    segments.join("/")
}

/// Normalize a single path segment (no slashes).
fn slugify_segment(segment: &str) -> String {
    let mut result = String::with_capacity(segment.len());

    for ch in segment.chars() {
        if ch.is_alphanumeric() {
            result.push(ch);
        } else if ch == ' ' || ch == '_' || ch == '-' {
            result.push('-');
        }
        // Other punctuation is dropped
    }

    // Collapse consecutive hyphens
    let mut collapsed = String::with_capacity(result.len());
    let mut prev_hyphen = false;
    for ch in result.chars() {
        if ch == '-' {
            if !prev_hyphen && !collapsed.is_empty() {
                collapsed.push('-');
            }
            prev_hyphen = true;
        } else {
            prev_hyphen = false;
            collapsed.push(ch);
        }
    }

    collapsed.trim_matches('-').to_string()
}

/// Convert a slug back to a title (best-effort reverse of slugify).
///
/// Replaces hyphens with spaces and capitalizes each word.
/// Handles folder prefixes by using only the last segment.
pub fn title_from_slug(slug: &str) -> String {
    let leaf = slug.rsplit('/').next().unwrap_or(slug);
    leaf.split('-')
        .filter(|s| !s.is_empty())
        .map(|word| {
            let mut chars = word.chars();
            match chars.next() {
                Some(c) => {
                    let upper: String = c.to_uppercase().collect();
                    format!("{upper}{}", chars.as_str())
                }
                None => String::new(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Extract the H1 title from markdown content, if present.
///
/// Looks for the first `# Title` line at the top of the document
/// (skipping blank lines). Returns `None` if no H1 is found before
/// the first non-blank, non-heading line.
pub fn extract_h1(content: &str) -> Option<String> {
    for line in content.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }
        if let Some(rest) = trimmed.strip_prefix("# ") {
            let title = rest.trim();
            if !title.is_empty() {
                return Some(title.to_string());
            }
        }
        // Stop at first non-blank, non-H1 line
        break;
    }
    None
}

/// Build a sorted list of byte ranges that are inside code (fenced blocks or inline spans).
///
/// Uses pulldown-cmark to correctly identify all code regions, including
/// indented code blocks, multi-backtick spans, and tilde fences.
fn code_byte_ranges(content: &str) -> Vec<(usize, usize)> {
    let parser = Parser::new_ext(content, Options::all()).into_offset_iter();
    let mut ranges = Vec::new();

    for (event, range) in parser {
        match event {
            Event::Start(Tag::CodeBlock(_)) | Event::Code(_) => {
                ranges.push((range.start, range.end));
            }
            _ => {}
        }
    }

    ranges
}

/// Check whether a byte offset falls inside any code range.
fn is_in_code(offset: usize, code_ranges: &[(usize, usize)]) -> bool {
    code_ranges.iter().any(|(s, e)| offset >= *s && offset < *e)
}

/// Compute the 1-based line number for a byte offset in content.
fn line_number_at(content: &str, byte_offset: usize) -> usize {
    content[..byte_offset].matches('\n').count() + 1
}

/// Extract all `\[\[wikilinks\]\]` from markdown content.
///
/// Uses pulldown-cmark to identify code blocks and inline code spans,
/// then scans non-code regions with regex. This correctly handles all
/// Markdown code constructs (fenced, indented, inline, multi-backtick).
pub fn extract_links(content: &str) -> Vec<WikiLink> {
    let code_ranges = code_byte_ranges(content);
    let mut links = Vec::new();

    for cap in WIKILINK_RE.captures_iter(content) {
        let m = cap.get(0).expect("Regex match should exist");

        if is_in_code(m.start(), &code_ranges) {
            continue;
        }

        let body = cap.get(1).expect("Capture group 1 should exist").as_str();
        let (target, alias) = parse_link_body(body);

        // Strip .md extension if present (users may write [[Page.md]] instead of [[Page]])
        let target_for_slug = if target.to_lowercase().ends_with(".md") {
            &target[..target.len() - 3]
        } else {
            &target
        };
        let slug = slugify(target_for_slug);

        if !slug.is_empty() {
            links.push(WikiLink {
                target,
                alias,
                slug,
                line_number: line_number_at(content, m.start()),
            });
        }
    }

    links
}

fn parse_link_body(body: &str) -> (String, Option<String>) {
    if let Some(pipe_pos) = body.find('|') {
        let target = body[..pipe_pos].trim().to_string();
        let alias = body[pipe_pos + 1..].trim().to_string();
        (target, Some(alias))
    } else {
        (body.trim().to_string(), None)
    }
}

/// Replace all `\[\[wikilinks\]\]` that resolve to `old_slug` with `new_title`.
/// Preserves aliases: `[[Old|alias]]` -> `[[New Title|alias]]`.
/// Uses pulldown-cmark to skip links inside code blocks and inline code spans.
pub fn replace_wikilinks(content: &str, old_slug: &str, new_title: &str) -> String {
    let code_ranges = code_byte_ranges(content);
    let mut result = String::with_capacity(content.len());
    let mut last_end = 0;

    for cap in WIKILINK_RE.captures_iter(content) {
        let m = cap.get(0).expect("Regex match should exist");
        let start = m.start();
        let end = m.end();

        if is_in_code(start, &code_ranges) {
            continue;
        }

        let body = cap.get(1).expect("Capture group 1 should exist").as_str();
        let (target, alias) = parse_link_body(body);
        let target_slug = slugify(&target);

        if target_slug == old_slug {
            result.push_str(&content[last_end..start]);

            match alias {
                Some(a) => result.push_str(&format!("[[{new_title}|{a}]]")),
                None => result.push_str(&format!("[[{new_title}]]")),
            }

            last_end = end;
        }
    }

    result.push_str(&content[last_end..]);
    result
}

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

    #[test]
    fn test_slugify_basic() {
        assert_eq!(slugify("My Page Name"), "my-page-name");
    }

    #[test]
    fn test_slugify_folder() {
        assert_eq!(slugify("folder/My Page"), "folder/my-page");
    }

    #[test]
    fn test_slugify_special_chars() {
        assert_eq!(slugify("Hello, World! (2024)"), "hello-world-2024");
    }

    #[test]
    fn test_slugify_underscores() {
        assert_eq!(slugify("my_page_name"), "my-page-name");
    }

    #[test]
    fn test_slugify_unicode() {
        assert_eq!(slugify("Tagesnotiz"), "tagesnotiz");
        assert_eq!(slugify("日本語ページ"), "日本語ページ");
    }

    #[test]
    fn test_slugify_whitespace() {
        assert_eq!(slugify("  spaces  everywhere  "), "spaces-everywhere");
    }

    #[test]
    fn test_extract_simple() {
        let links = extract_links("see [[Page One]] here");
        assert_eq!(links.len(), 1);
        assert_eq!(links[0].target, "Page One");
        assert_eq!(links[0].slug, "page-one");
        assert_eq!(links[0].alias, None);
        assert_eq!(links[0].line_number, 1);
    }

    #[test]
    fn test_extract_alias() {
        let links = extract_links("see [[Page One|click here]]");
        assert_eq!(links.len(), 1);
        assert_eq!(links[0].target, "Page One");
        assert_eq!(links[0].alias, Some("click here".to_string()));
        assert_eq!(links[0].slug, "page-one");
    }

    #[test]
    fn test_extract_multiple() {
        let links = extract_links("[[A]] and [[B|bee]] plus [[folder/C]]");
        assert_eq!(links.len(), 3);
        assert_eq!(links[0].slug, "a");
        assert_eq!(links[1].slug, "b");
        assert_eq!(links[1].alias, Some("bee".to_string()));
        assert_eq!(links[2].slug, "folder/c");
    }

    #[test]
    fn test_extract_in_fenced_code_block() {
        let content = "before\n```\n[[not a link]]\n```\nafter [[real link]]";
        let links = extract_links(content);
        assert_eq!(links.len(), 1);
        assert_eq!(links[0].slug, "real-link");
    }

    #[test]
    fn test_extract_in_inline_code() {
        let links = extract_links("see `[[not a link]]` here");
        assert_eq!(links.len(), 0);
    }

    #[test]
    fn test_extract_line_numbers() {
        let content = "line one\n[[Link A]]\nline three\nline four\n[[Link B]]";
        let links = extract_links(content);
        assert_eq!(links.len(), 2);
        assert_eq!(links[0].line_number, 2);
        assert_eq!(links[1].line_number, 5);
    }

    #[test]
    fn test_nested_brackets_no_panic() {
        let links = extract_links("[[outer [[inner]] end]]");
        assert!(links.len() <= 2);
    }

    #[test]
    fn test_empty_link_ignored() {
        let links = extract_links("[[]]");
        assert_eq!(links.len(), 0);
    }

    #[test]
    fn test_replace_simple() {
        let result = replace_wikilinks("see [[Rust]] here", "rust", "Rust Language");
        assert_eq!(result, "see [[Rust Language]] here");
    }

    #[test]
    fn test_replace_preserves_alias() {
        let result = replace_wikilinks("see [[Rust|my fav]] here", "rust", "Rust Language");
        assert_eq!(result, "see [[Rust Language|my fav]] here");
    }

    #[test]
    fn test_replace_skips_code_block() {
        let content = "before [[Rust]]\n```\n[[Rust]]\n```\nafter [[Rust]]";
        let result = replace_wikilinks(content, "rust", "Rust Language");
        assert_eq!(
            result,
            "before [[Rust Language]]\n```\n[[Rust]]\n```\nafter [[Rust Language]]"
        );
    }

    #[test]
    fn test_replace_skips_inline_code() {
        let result = replace_wikilinks("see `[[Rust]]` and [[Rust]]", "rust", "Rust Language");
        assert_eq!(result, "see `[[Rust]]` and [[Rust Language]]");
    }

    #[test]
    fn test_slugify_spaces_only() {
        assert_eq!(slugify("   "), "");
    }

    #[test]
    fn test_slugify_punctuation_only() {
        assert_eq!(slugify("!@#$%"), "");
    }

    #[test]
    fn test_title_from_slug_basic() {
        assert_eq!(title_from_slug("my-page"), "My Page");
    }

    #[test]
    fn test_title_from_slug_with_folder() {
        assert_eq!(title_from_slug("notes/deep/my-page"), "My Page");
    }

    #[test]
    fn test_title_from_slug_single_word() {
        assert_eq!(title_from_slug("cael"), "Cael");
    }

    #[test]
    fn test_extract_h1_basic() {
        assert_eq!(extract_h1("# My Title\n\nContent here"), Some("My Title".to_string()));
    }

    #[test]
    fn test_extract_h1_with_leading_blanks() {
        assert_eq!(extract_h1("\n\n# Title\nContent"), Some("Title".to_string()));
    }

    #[test]
    fn test_extract_h1_none_without_h1() {
        assert_eq!(extract_h1("No heading here\nJust text"), None);
    }

    #[test]
    fn test_extract_h1_ignores_h2() {
        assert_eq!(extract_h1("## Not an H1"), None);
    }

    #[test]
    fn test_extract_h1_ignores_deep_h1() {
        // H1 after non-blank non-heading line should not match
        assert_eq!(extract_h1("Some text\n# Not the title"), None);
    }

    #[test]
    fn test_extract_h1_empty_content() {
        assert_eq!(extract_h1(""), None);
        assert_eq!(extract_h1("\n\n\n"), None);
    }

    // --- Slugify segment-awareness tests ---

    #[test]
    fn test_slugify_idempotent() {
        let cases = ["My Page", "folder/My Page", "a b c", "日本語ページ", "C++ Guide"];
        for input in &cases {
            let once = slugify(input);
            let twice = slugify(&once);
            assert_eq!(once, twice, "slugify not idempotent for: {input}");
        }
    }

    #[test]
    fn test_slugify_double_slash() {
        assert_eq!(slugify("folder//page"), "folder/page");
    }

    #[test]
    fn test_slugify_leading_trailing_slash() {
        assert_eq!(slugify("/page/"), "page");
        assert_eq!(slugify("/folder/page/"), "folder/page");
    }

    #[test]
    fn test_slugify_slash_only() {
        assert_eq!(slugify("/"), "");
        assert_eq!(slugify("///"), "");
    }

    // --- pulldown-cmark code detection tests ---

    #[test]
    fn test_extract_skips_indented_code_block() {
        let content = "normal text\n\n    [[not a link]]\n\nreal [[link]]";
        let links = extract_links(content);
        assert_eq!(links.len(), 1);
        assert_eq!(links[0].slug, "link");
    }

    #[test]
    fn test_extract_skips_tilde_fence() {
        let content = "before\n~~~\n[[not a link]]\n~~~\nafter [[real]]";
        let links = extract_links(content);
        assert_eq!(links.len(), 1);
        assert_eq!(links[0].slug, "real");
    }

    #[test]
    fn test_extract_skips_multi_backtick_inline() {
        let content = "see ``[[not a link]]`` and [[real]]";
        let links = extract_links(content);
        assert_eq!(links.len(), 1);
        assert_eq!(links[0].slug, "real");
    }

    #[test]
    fn test_replace_skips_indented_code_block() {
        let content = "[[Rust]]\n\n    [[Rust]]\n\n[[Rust]]";
        let result = replace_wikilinks(content, "rust", "Rust Language");
        assert!(result.contains("[[Rust Language]]"));
        // The indented block should preserve the original
        assert!(result.contains("    [[Rust]]"));
    }
}