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.mdindex 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### Changeddiff --git a/crates/ai-memory-web/src/markdown.rs b/crates/ai-memory-web/src/markdown.rsindex 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.rsindex 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<Lcontinue;}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).");+ }}