Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(wiki,web): CommonMark link destination conformance, code-fence tracking, and relative link resolution

Vinícius Andrade8e5a84b9cc53
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf0c92f3..4f00da13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+- Conformance to CommonMark §4.5 and §4.7 in wiki markdown link extraction,
+ code-fence tracking, and web relative link resolution:
+ - Code fence tracking in `extract_links` and `rewrite_local_wikilinks` now
+ matches the opening delimiter glyph (`` ` `` vs `~`) and length per
+ CommonMark §4.5 via `CodeFence::step`, preventing inner fences of different
+ glyph or shorter length from prematurely toggling fence state.
+ - Markdown link destination parsing in `extract_links` now conforms to
+ CommonMark §4.7: balanced parentheses in bare destinations are preserved
+ instead of truncating at the first `)` (e.g. `[doc](notes/foo_(1).md)` is
+ now correctly indexed), pointy-bracketed destinations (`<...>`) are supported,
+ and optional trailing link titles are properly stepped over.
+ - Wikilink export rewrite in `rewrite_local_wikilinks` now wraps destinations
+ containing spaces in pointy brackets (`[label](<../path with space.md>)`),
+ ensuring standard CommonMark conformance and OKF v0.2 interoperability.
+ - The `/web` reader's `scope_relative_link` now strips pointy brackets and
+ leading `./` prefixes (e.g. `[doc](./notes/foo.md)`), resolving to valid
+ `PagePath`s without failing path segment validation.
+
## [2.4.2] - 2026-09-29
### Changed
diff --git a/crates/ai-memory-web/src/markdown.rs b/crates/ai-memory-web/src/markdown.rs
index af57bf21..412fc22f 100644
--- a/crates/ai-memory-web/src/markdown.rs
+++ b/crates/ai-memory-web/src/markdown.rs
@@ -60,7 +60,10 @@ fn options() -> Options {
/// relative — the same convention `[[wikilinks]]` use — which is what the
/// OKF bundle-index page and generated cross-references rely on (#603).
fn scope_relative_link<'a>(dest: CowStr<'a>, workspace: &str, project: &str) -> CowStr<'a> {
- let trimmed = dest.trim();
+ let mut trimmed = dest.trim();
+ if let Some(stripped) = trimmed.strip_prefix('<').and_then(|s| s.strip_suffix('>')) {
+ trimmed = stripped.trim();
+ }
// Leave anchors, absolute paths, network paths, and any scheme
// (http:, mailto:, javascript:, …) to safe_url.
if trimmed.is_empty()
@@ -85,8 +88,11 @@ fn scope_relative_link<'a>(dest: CowStr<'a>, workspace: &str, project: &str) ->
if path_part.is_empty() || path_part.contains("..") {
return dest; // don't rewrite traversal; safe_url/router will reject
}
- let path_part = path_part.trim_end_matches('/');
- if path_part.is_empty() {
+ let mut path_part = path_part.trim_end_matches('/');
+ while let Some(rest) = path_part.strip_prefix("./") {
+ path_part = rest;
+ }
+ if path_part.is_empty() || path_part == "." {
return dest;
}
CowStr::Boxed(
@@ -801,4 +807,21 @@ mod tests {
);
}
}
+
+ #[test]
+ fn relative_link_with_leading_dot_slash_resolves() {
+ let html = render(
+ "[doc](./notes/foo.md) and [pointy](<./notes/bar.md>)",
+ "default",
+ "scratch",
+ );
+ assert!(
+ html.contains(r#"href="w/default/scratch/p/notes/foo.md""#),
+ "leading ./ must be stripped: {html}"
+ );
+ assert!(
+ html.contains(r#"href="w/default/scratch/p/notes/bar.md""#),
+ "pointy brackets and leading ./ must resolve: {html}"
+ );
+ }
}
diff --git a/crates/ai-memory-wiki/src/markdown.rs b/crates/ai-memory-wiki/src/markdown.rs
index dff16889..74c65eff 100644
--- a/crates/ai-memory-wiki/src/markdown.rs
+++ b/crates/ai-memory-wiki/src/markdown.rs
@@ -136,18 +136,51 @@ type LinkKey = (Option<String>, Option<String>, String);
/// so is anything inside a fenced block or an inline code span, which the
/// page shows as code rather than as a link.
/// Returned values are normalised to wiki-root-relative [`LinkTarget`]s.
+/// Active code fence delimiter and its opening run length (CommonMark §4.5).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+struct CodeFence {
+ glyph: char,
+ len: usize,
+}
+
+impl CodeFence {
+ /// Update the fence state based on `line`.
+ ///
+ /// Returns `(updated_fence_state, line_is_code_or_fence)`.
+ fn step(current: Option<Self>, line: &str) -> (Option<Self>, bool) {
+ let trimmed = line.trim_start();
+ if trimmed.starts_with("```") || trimmed.starts_with("~~~") {
+ let glyph = trimmed.chars().next().unwrap();
+ let count = trimmed.chars().take_while(|&c| c == glyph).count();
+ match current {
+ None => (Some(CodeFence { glyph, len: count }), true),
+ Some(fence) => {
+ if fence.glyph == glyph
+ && count >= fence.len
+ && trimmed[count..].trim().is_empty()
+ {
+ (None, true)
+ } else {
+ (Some(fence), true)
+ }
+ }
+ }
+ } else {
+ let in_fence = current.is_some();
+ (current, in_fence)
+ }
+ }
+}
+
#[must_use]
pub fn extract_links(body: &str, page_path: &PagePath) -> Vec<LinkTarget> {
let mut out: BTreeSet<LinkKey> = BTreeSet::new();
- let mut in_fence = false;
+ let mut fence: Option<CodeFence> = None;
for line in body.lines() {
- let trimmed = line.trim_start();
- if trimmed.starts_with("```") || trimmed.starts_with("~~~") {
- in_fence = !in_fence;
- continue;
- }
- if in_fence {
+ let (next_fence, is_fence_or_code) = CodeFence::step(fence, line);
+ fence = next_fence;
+ if is_fence_or_code {
continue;
}
let line = blank_inline_code(line);
@@ -397,17 +430,12 @@ fn split_scope(target: &str) -> LinkKey {
#[must_use]
pub fn rewrite_local_wikilinks(body: &str, page_path: &PagePath, own_project: &str) -> String {
let mut out = String::with_capacity(body.len() + 64);
- let mut in_fence = false;
+ let mut fence: Option<CodeFence> = None;
for raw_line in body.split_inclusive('\n') {
let (line, terminator) = split_line_terminator(raw_line);
- let trimmed = line.trim_start();
- if trimmed.starts_with("```") || trimmed.starts_with("~~~") {
- in_fence = !in_fence;
- out.push_str(line);
- out.push_str(terminator);
- continue;
- }
- if in_fence {
+ let (next_fence, is_fence_or_code) = CodeFence::step(fence, line);
+ fence = next_fence;
+ if is_fence_or_code {
out.push_str(line);
out.push_str(terminator);
continue;
@@ -470,7 +498,13 @@ fn rewrite_wikilinks_in_segment(
out.push('[');
out.push_str(&escape_markdown_link_label(&label));
out.push_str("](");
- out.push_str(&href);
+ if href.contains(' ') {
+ out.push('<');
+ out.push_str(&href);
+ out.push('>');
+ } else {
+ out.push_str(&href);
+ }
out.push(')');
}
None => {
@@ -590,15 +624,47 @@ fn extract_markdown_links(line: &str, page_path: &PagePath, out: &mut BTreeSet<L
continue;
}
let target_start = close + 2;
- let Some(rel_end) = line[target_start..].find(')') else {
- break;
+ let Some((raw, target_end)) = parse_link_destination(&line[target_start..]) else {
+ start_at = close + 1;
+ continue;
};
- let target_end = target_start + rel_end;
- let raw = &line[target_start..target_end];
if let Some(path) = normalize_link_target(raw, page_path, false) {
out.insert((None, None, path));
}
- start_at = target_end + 1;
+ start_at = target_start + target_end + 1;
+ }
+}
+
+/// Parse a CommonMark link destination immediately following the opening `(`
+/// of `[label](<destination>)` or `[label](destination)` (CommonMark §4.7).
+///
+/// Returns `(destination_str, closing_paren_byte_offset)`.
+fn parse_link_destination(rest: &str) -> Option<(&str, usize)> {
+ let trimmed = rest.trim_start();
+ let leading = rest.len() - trimmed.len();
+ if let Some(after_lt) = trimmed.strip_prefix('<') {
+ let rel_gt = after_lt.find('>')?;
+ let after_gt = &after_lt[rel_gt + 1..];
+ let rel_paren = after_gt.find(')')?;
+ let paren = leading + 1 + rel_gt + 1 + rel_paren;
+ Some((&after_lt[..rel_gt], paren))
+ } else {
+ let mut depth = 1;
+ let mut dest_end = None;
+ for (i, b) in trimmed.char_indices() {
+ if b == '(' {
+ depth += 1;
+ } else if b == ')' {
+ depth -= 1;
+ if depth == 0 {
+ let end = dest_end.unwrap_or(i);
+ return Some((&trimmed[..end], leading + i));
+ }
+ } else if b.is_ascii_whitespace() && depth == 1 && dest_end.is_none() {
+ dest_end = Some(i);
+ }
+ }
+ None
}
}
@@ -1109,4 +1175,52 @@ mod tests {
let _ = rewrite_local_wikilinks(body, &path, "proj");
}
}
+
+ #[test]
+ fn code_fence_respects_glyph_and_length() {
+ let md = "~~~\n[[a/b.md]]\n```\n[[c/d.md]]\n~~~\nafter [[e/f.md]]\n";
+ let path = PagePath::new("concepts/a.md").unwrap();
+ let links = extract_links(md, &path);
+ assert_eq!(links.len(), 1, "only link outside fence extracted");
+ assert_eq!(links[0].path.as_str(), "e/f.md");
+
+ let rewritten = rewrite_local_wikilinks(md, &path, "proj");
+ assert!(rewritten.contains("[[a/b.md]]"), "a/b remains literal");
+ assert!(rewritten.contains("[[c/d.md]]"), "c/d remains literal");
+ assert!(
+ rewritten.contains("[e/f.md](../e/f.md)"),
+ "post-fence wikilink rewritten: {rewritten}"
+ );
+
+ // 4 backticks cannot be closed by 3 backticks
+ let md4 = "````\n[[inside4.md]]\n```\n[[still_inside.md]]\n````\nafter [[outside.md]]\n";
+ let links4 = extract_links(md4, &path);
+ assert_eq!(links4.len(), 1);
+ assert_eq!(links4[0].path.as_str(), "outside.md");
+ }
+
+ #[test]
+ fn extract_links_parses_balanced_parentheses_and_pointy_destinations() {
+ let root = PagePath::new("here.md").unwrap();
+ let md = "See [doc](notes/foo_(1).md), [space](<notes/bar (2).md>), and [title](notes/baz.md \"a title\").\n";
+ let links = extract_links(md, &root);
+ assert_eq!(links.len(), 3, "{links:?}");
+ assert!(links.iter().any(|l| l.path.as_str() == "notes/foo_(1).md"));
+ assert!(links.iter().any(|l| l.path.as_str() == "notes/bar (2).md"));
+ assert!(links.iter().any(|l| l.path.as_str() == "notes/baz.md"));
+ }
+
+ #[test]
+ fn rewrite_local_wikilinks_encloses_destinations_with_spaces_in_pointy_brackets() {
+ let path = PagePath::new("concepts/a.md").unwrap();
+ let rewritten = rewrite_local_wikilinks("See [[decisions/my decision.md]].", &path, "proj");
+ assert_eq!(
+ rewritten,
+ "See [decisions/my decision.md](<../decisions/my decision.md>)."
+ );
+
+ // Without spaces, no pointy brackets needed
+ let plain = rewrite_local_wikilinks("See [[decisions/b.md]].", &path, "proj");
+ assert_eq!(plain, "See [decisions/b.md](../decisions/b.md).");
+ }
}