use std::ops::Range;
use std::path::{Component, Path, PathBuf};
use pulldown_cmark::{Event, LinkType, Parser, Tag, TagEnd};
use crate::config::schema::FilesConfig;
use crate::doc::document::parser_options;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LinkKind {
Inline,
Autolink,
Wiki,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Link {
pub text: String,
pub target: String,
pub range: Range<usize>,
pub kind: LinkKind,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Resolved {
Document {
path: PathBuf,
anchor: Option<String>,
},
Anchor {
slug: String,
},
Directory {
path: PathBuf,
},
External {
url: String,
},
Other {
path: PathBuf,
},
Broken {
target: String,
},
}
pub fn extract(source: &str) -> Vec<Link> {
let (mut links, verbatim) = extract_markdown(source);
links.extend(extract_wiki(source, &verbatim));
links.sort_by_key(|link| link.range.start);
links
}
fn extract_markdown(source: &str) -> (Vec<Link>, Vec<Range<usize>>) {
let mut links = Vec::new();
let mut verbatim = Vec::new();
let mut open: Option<(Range<usize>, String, LinkKind, String)> = None;
for (event, range) in Parser::new_ext(source, parser_options()).into_offset_iter() {
match event {
Event::Start(Tag::Link {
link_type,
dest_url,
..
}) => {
let kind = match link_type {
LinkType::Autolink | LinkType::Email => LinkKind::Autolink,
_ => LinkKind::Inline,
};
open = Some((range, dest_url.into_string(), kind, String::new()));
}
Event::End(TagEnd::Link) => {
if let Some((range, target, kind, text)) = open.take() {
links.push(Link {
text: if text.trim().is_empty() {
target.clone()
} else {
text
},
target,
range,
kind,
});
}
}
Event::Code(text) => {
verbatim.push(range);
if let Some((_, _, _, collected)) = &mut open {
collected.push_str(&text);
}
}
Event::Text(text) => {
if let Some((_, _, _, collected)) = &mut open {
collected.push_str(&text);
}
}
Event::Start(Tag::CodeBlock(_)) | Event::Start(Tag::MetadataBlock(_)) => {
verbatim.push(range);
}
Event::Html(_) | Event::InlineHtml(_) => verbatim.push(range),
_ => {}
}
}
(links, verbatim)
}
fn extract_wiki(source: &str, verbatim: &[Range<usize>]) -> Vec<Link> {
let bytes = source.as_bytes();
let mut links = Vec::new();
let mut at = 0usize;
while let Some(found) = source[at..].find("[[") {
let start = at + found;
at = start + 2;
let Some(end) = source[at..].find("]]") else {
break;
};
let end = at + end;
let inner = &source[at..end];
at = end + 2;
if verbatim.iter().any(|range| range.contains(&start)) {
continue;
}
if inner.contains('\n') || inner.trim().is_empty() {
continue;
}
let range = if start > 0 && bytes[start - 1] == b'!' {
start - 1..at
} else {
start..at
};
let (target, display) = split_wiki(inner);
links.push(Link {
text: display,
target,
range,
kind: LinkKind::Wiki,
});
}
links
}
fn split_wiki(inner: &str) -> (String, String) {
let (target, display) = match inner.split_once('|') {
Some((target, display)) => (target.trim(), Some(display.trim())),
None => (inner.trim(), None),
};
let shown = display
.filter(|d| !d.is_empty())
.map(str::to_string)
.unwrap_or_else(|| {
target.replace('#', " § ")
});
(target.to_string(), shown)
}
pub fn resolve(
target: &str,
document_dir: &Path,
vault_root: &Path,
files: &FilesConfig,
) -> Resolved {
let raw = target.trim();
if raw.is_empty() {
return broken(target);
}
if is_external(raw) {
return Resolved::External {
url: raw.to_string(),
};
}
let (path_part, fragment) = split_fragment(raw);
if path_part.is_empty() {
return match fragment {
Some(slug) if !slug.is_empty() => Resolved::Anchor { slug },
_ => broken(target),
};
}
let path_part = path_part.replace('\\', "/");
let decoded = percent_decode(&path_part);
let relative = Path::new(&decoded);
let candidates: Vec<PathBuf> = if let Ok(rooted) = relative.strip_prefix("/") {
vec![normalise(&vault_root.join(rooted)), relative.to_path_buf()]
} else {
vec![normalise(&document_dir.join(relative))]
};
for candidate in candidates {
let Ok(metadata) = std::fs::metadata(&candidate) else {
continue;
};
if metadata.is_dir() {
return Resolved::Directory { path: candidate };
}
return if files.is_markdown(&candidate) {
Resolved::Document {
path: candidate,
anchor: fragment.filter(|f| !f.is_empty()),
}
} else {
Resolved::Other { path: candidate }
};
}
broken(target)
}
fn broken(target: &str) -> Resolved {
Resolved::Broken {
target: target.trim().to_string(),
}
}
pub fn is_external(target: &str) -> bool {
let Some(colon) = target.find(':') else {
return false;
};
let scheme = &target[..colon];
if scheme.len() < 2 {
return false;
}
let mut chars = scheme.chars();
chars.next().is_some_and(|c| c.is_ascii_alphabetic())
&& chars.all(|c| c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.'))
}
fn split_fragment(target: &str) -> (&str, Option<String>) {
match target.find('#') {
Some(at) => (
&target[..at],
Some(percent_decode(&target[at + 1..]).to_lowercase()),
),
None => (target, None),
}
}
fn percent_decode(text: &str) -> String {
if !text.contains('%') {
return text.to_string();
}
let bytes = text.as_bytes();
let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'%' && i + 2 < bytes.len() {
let hex = std::str::from_utf8(&bytes[i + 1..i + 3]).ok();
if let Some(byte) = hex.and_then(|h| u8::from_str_radix(h, 16).ok()) {
out.push(byte);
i += 3;
continue;
}
}
out.push(bytes[i]);
i += 1;
}
String::from_utf8_lossy(&out).into_owned()
}
pub fn normalise(path: &Path) -> PathBuf {
let mut out = PathBuf::new();
for component in path.components() {
match component {
Component::CurDir => {}
Component::ParentDir => {
if !out.pop() {
out.push(Component::ParentDir);
}
}
other => out.push(other),
}
}
if out.as_os_str().is_empty() {
out.push(Component::CurDir);
}
out
}
#[cfg(test)]
mod tests {
use super::*;
fn vault() -> PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/vault")
}
fn resolve_from(dir: &str, target: &str) -> Resolved {
resolve(
target,
&vault().join(dir),
&vault(),
&FilesConfig::default(),
)
}
#[test]
fn links_come_out_in_reading_order_with_their_text() {
let links = extract("See [one](a.md) and then [two](b.md).");
assert_eq!(links.len(), 2);
assert_eq!(links[0].text, "one");
assert_eq!(links[0].target, "a.md");
assert_eq!(links[1].text, "two");
assert_eq!(links[1].kind, LinkKind::Inline);
}
#[test]
fn the_range_covers_the_whole_link() {
let source = "before [text](target.md) after";
let links = extract(source);
assert_eq!(&source[links[0].range.clone()], "[text](target.md)");
}
#[test]
fn markup_inside_the_text_is_flattened() {
let links = extract("[a **bold** `word`](x.md)");
assert_eq!(links[0].text, "a bold word");
}
#[test]
fn autolinks_are_marked_as_such() {
let links = extract("<https://example.com> and <a@example.com>");
assert_eq!(links.len(), 2);
assert!(links.iter().all(|l| l.kind == LinkKind::Autolink));
assert_eq!(links[1].target, "a@example.com");
}
#[test]
fn a_reference_link_resolves_to_its_definition() {
let links = extract("[text][ref]\n\n[ref]: target.md\n");
assert_eq!(links.len(), 1);
assert_eq!(links[0].target, "target.md");
}
#[test]
fn an_image_link_shows_the_alt_text() {
let links = extract("[](target.md)");
assert_eq!(links[0].text, "alt");
assert_eq!(links[0].target, "target.md");
}
#[test]
fn a_link_with_no_text_at_all_falls_back_to_its_target() {
let links = extract("[](target.md)");
assert_eq!(links[0].text, "target.md");
}
#[test]
fn a_document_with_no_links_produces_none() {
assert!(extract("# Heading\n\nJust prose.\n").is_empty());
}
#[test]
fn all_four_wiki_spellings_are_recognised() {
let links = extract(
"[[Page Name]], [[Page Name|Display Text]], [[Page#Heading]], and \
[[folder/Page Name]].",
);
assert_eq!(links.len(), 4);
assert!(links.iter().all(|l| l.kind == LinkKind::Wiki));
assert_eq!(links[0].target, "Page Name");
assert_eq!(links[0].text, "Page Name");
assert_eq!(links[1].target, "Page Name");
assert_eq!(links[1].text, "Display Text");
assert_eq!(links[2].target, "Page#Heading");
assert_eq!(links[2].text, "Page § Heading");
assert_eq!(links[3].target, "folder/Page Name");
}
#[test]
fn a_display_text_containing_a_hash_is_not_a_heading() {
let links = extract("[[Page|Issue #1]]");
assert_eq!(links[0].target, "Page");
assert_eq!(links[0].text, "Issue #1");
}
#[test]
fn a_wiki_link_in_code_is_left_as_text() {
let inline = extract("Write `[[Page]]` to link.");
assert!(inline.is_empty(), "{inline:?}");
let fenced = extract("```\n[[Page]]\n```\n");
assert!(fenced.is_empty(), "{fenced:?}");
}
#[test]
fn an_embed_is_treated_as_a_link_to_the_page() {
let links = extract("![[Diagram]]");
assert_eq!(links.len(), 1);
assert_eq!(links[0].target, "Diagram");
assert_eq!(&"![[Diagram]]"[links[0].range.clone()], "![[Diagram]]");
}
#[test]
fn unclosed_and_empty_brackets_are_not_links() {
assert!(extract("[[unclosed").is_empty());
assert!(extract("[[]]").is_empty());
assert!(extract("[[ ]]").is_empty());
assert!(extract("[[spans\na newline]]").is_empty());
}
#[test]
fn wiki_and_inline_links_come_back_in_one_reading_order() {
let links = extract("[first](a.md) then [[Second]] then [third](c.md)");
assert_eq!(links.len(), 3);
assert_eq!(links[0].target, "a.md");
assert_eq!(links[1].target, "Second");
assert_eq!(links[2].target, "c.md");
}
#[test]
fn a_relative_target_resolves_against_the_documents_own_directory() {
assert_eq!(
resolve_from("docs/api", "errors.md"),
Resolved::Document {
path: vault().join("docs/api/errors.md"),
anchor: None,
}
);
}
#[test]
fn a_target_two_directories_up_and_one_down_resolves() {
assert_eq!(
resolve_from("docs/api", "../../docs/guides/setup.md"),
Resolved::Document {
path: vault().join("docs/guides/setup.md"),
anchor: None,
}
);
}
#[test]
fn an_anchor_is_carried_through_and_lower_cased() {
assert_eq!(
resolve_from("docs/api", "auth.md#Obtaining-A-Token"),
Resolved::Document {
path: vault().join("docs/api/auth.md"),
anchor: Some("obtaining-a-token".to_string()),
}
);
}
#[test]
fn a_bare_fragment_stays_in_the_current_document() {
assert_eq!(
resolve_from("docs/api", "#obtaining-a-token"),
Resolved::Anchor {
slug: "obtaining-a-token".to_string(),
}
);
}
#[test]
fn a_leading_slash_is_tried_against_the_vault_root() {
assert_eq!(
resolve_from("docs/api", "/README.md"),
Resolved::Document {
path: vault().join("README.md"),
anchor: None,
}
);
}
#[test]
fn a_directory_target_is_reported_as_a_directory() {
assert_eq!(
resolve_from("", "docs/api"),
Resolved::Directory {
path: vault().join("docs/api"),
}
);
}
#[test]
fn a_non_markdown_target_is_reported_separately() {
assert_eq!(
resolve_from("", ".gitignore"),
Resolved::Other {
path: vault().join(".gitignore"),
}
);
}
#[test]
fn url_encoded_names_are_decoded_before_they_are_looked_up() {
assert_eq!(
resolve_from("", "spaces%20and%20%23hash/awkward%20ışık%20%231.md"),
Resolved::Document {
path: vault().join("spaces and #hash/awkward ışık #1.md"),
anchor: None,
}
);
}
#[test]
fn windows_separators_are_accepted() {
assert_eq!(
resolve_from("docs", "api\\auth.md"),
Resolved::Document {
path: vault().join("docs/api/auth.md"),
anchor: None,
}
);
}
#[test]
fn external_schemes_are_recognised_and_not_touched() {
for url in [
"https://example.com/a?b=c#d",
"http://example.com",
"mailto:someone@example.com",
] {
assert_eq!(
resolve_from("", url),
Resolved::External {
url: url.to_string()
}
);
}
}
#[test]
fn a_windows_drive_is_not_mistaken_for_a_url_scheme() {
assert!(!is_external("C:/notes/file.md"));
assert!(is_external("https://example.com"));
assert!(!is_external("./relative.md"));
assert!(!is_external("no-colon-here"));
}
#[test]
fn an_unresolvable_target_is_broken_and_nothing_is_created() {
let missing = vault().join("docs/nowhere.md");
assert_eq!(
resolve_from("docs", "nowhere.md"),
Resolved::Broken {
target: "nowhere.md".to_string(),
}
);
assert!(!missing.exists(), "resolution must never create a file");
}
#[test]
fn an_empty_target_is_broken() {
assert_eq!(
resolve_from("", " "),
Resolved::Broken {
target: String::new(),
}
);
}
#[test]
fn a_target_outside_the_vault_still_resolves() {
let outside = resolve(
"../../../../README.md",
&vault().join("docs"),
&vault(),
&FilesConfig::default(),
);
assert_eq!(
outside,
Resolved::Document {
path: Path::new(env!("CARGO_MANIFEST_DIR")).join("README.md"),
anchor: None,
}
);
}
#[test]
fn normalisation_collapses_dots() {
assert_eq!(
normalise(Path::new("/a/b/../c/./d")),
PathBuf::from("/a/c/d")
);
assert_eq!(normalise(Path::new("a/../../b")), PathBuf::from("../b"));
assert_eq!(normalise(Path::new("./")), PathBuf::from("."));
}
#[test]
fn percent_decoding_leaves_malformed_escapes_alone() {
assert_eq!(percent_decode("a%20b"), "a b");
assert_eq!(percent_decode("100%"), "100%");
assert_eq!(percent_decode("%zz"), "%zz");
assert_eq!(percent_decode("plain"), "plain");
}
}