fix: use single-pass fenced-code + HTML comment stripping

altierac · altierac · commit a010b08e9056 · 2026-04-29T18:06:50.000+02:00
Replace separate .replace() calls for fenced code blocks and HTML
comments with a combined alternation pattern (FENCED_OR_COMMENT_PATTERN).

The previous two-pass approach had an ordering problem: stripping HTML
comments first could eat a real link when a &lt;!-- opener appeared inside
a fenced code block, and stripping fenced code first could eat a link
when a backtick fence appeared inside an HTML comment. The single-pass
alternation lets the regex engine pick whichever construct starts first
at each position, matching CommonMark precedence.

Also adds a regression test for the &lt;!-- inside fenced code case and
relaxes the mixed-content link order assertion (extraction order is an
implementation detail, not a contract).

Addresses ClawSweeper review feedback on strip-order concern.
diff --git a/extensions/memory-wiki/src/markdown.test.ts b/extensions/memory-wiki/src/markdown.test.ts
@@ -67,11 +67,7 @@ describe("extractWikiLinks", () => {
   });
 
   it("ignores links inside longer fences", () => {
-    const md = [
-      "````text",
-      "[label](target)",
-      "````",
-    ].join("\n");
+    const md = ["````text", "[label](target)", "````"].join("\n");
     expect(extractWikiLinks(md)).toEqual([]);
   });
 
@@ -104,7 +100,10 @@ describe("extractWikiLinks", () => {
       "",
       "![img](image.png)",
     ].join("\n");
-    expect(extractWikiLinks(md)).toEqual(["sources/real-page", "sources/other-page"]);
+    expect(extractWikiLinks(md)).toEqual(
+      expect.arrayContaining(["sources/real-page", "sources/other-page"]),
+    );
+    expect(extractWikiLinks(md)).toHaveLength(2);
   });
 
   it("skips external URLs", () => {
@@ -118,33 +117,24 @@ describe("extractWikiLinks", () => {
   });
 
   it("ignores links in fenced blocks with longer closing fence", () => {
-    const md = [
-      "```py",
-      "[fake](bad)",
-      "````",
-      "[real](sources/good)",
-    ].join("\n");
+    const md = ["```py", "[fake](bad)", "````", "[real](sources/good)"].join("\n");
     expect(extractWikiLinks(md)).toEqual(["sources/good"]);
   });
 
   it("ignores links in indented fenced blocks", () => {
-    const md = [
-      "  ```py",
-      "  [fake](bad)",
-      "  ```",
-      "[real](sources/good)",
-    ].join("\n");
+    const md = ["  ```py", "  [fake](bad)", "  ```", "[real](sources/good)"].join("\n");
     expect(extractWikiLinks(md)).toEqual(["sources/good"]);
   });
 
   it("does not swallow real links when fence opener is inside HTML comment", () => {
-    const md = [
-      "<!--",
-      "```",
-      "-->",
-      "[real](sources/good)",
-      "```",
-    ].join("\n");
+    const md = ["<!--", "```", "-->", "[real](sources/good)", "```"].join("\n");
+    expect(extractWikiLinks(md)).toEqual(["sources/good"]);
+  });
+
+  it("does not swallow real links when HTML comment opener is inside fenced code", () => {
+    const md = ["```", "<!--", "```", "[real](sources/good)", "<!-- a proper comment -->"].join(
+      "\n",
+    );
     expect(extractWikiLinks(md)).toEqual(["sources/good"]);
   });
 });
diff --git a/extensions/memory-wiki/src/markdown.ts b/extensions/memory-wiki/src/markdown.ts
@@ -62,8 +62,16 @@ export type WikiPageSummary = {
 const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n?/;
 const OBSIDIAN_LINK_PATTERN = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
 const MARKDOWN_LINK_PATTERN = /\[[^\]]+\]\(([^)]+)\)/g;
-const FENCED_CODE_PATTERN = /^( {0,3})`{3,}[^\n]*\n[\s\S]*?\n {0,3}`{3,}\s*$/gm;
-const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
+
+/**
+ * Combined pattern that strips fenced code blocks and HTML comments in a
+ * single pass so that neither construct can "shadow" the other.  Because the
+ * regex engine evaluates alternatives left-to-right at each position, the
+ * first matching construct in the text wins – exactly the precedence
+ * CommonMark specifies.
+ */
+const FENCED_OR_COMMENT_PATTERN =
+  /(?:^( {0,3})`{3,}[^\n]*\n[\s\S]*?\n {0,3}`{3,}\s*$)|(?:<!--[\s\S]*?-->)/gm;
 const IMAGE_LINK_PATTERN = /!\[[^\]]*\]\([^)]+\)/g;
 const RELATED_BLOCK_PATTERN = new RegExp(
   `${WIKI_RELATED_START_MARKER}[\\s\\S]*?${WIKI_RELATED_END_MARKER}`,
@@ -219,8 +227,7 @@ export function normalizeWikiClaims(value: unknown): WikiClaim[] {
 export function extractWikiLinks(markdown: string): string[] {
   const searchable = markdown
     .replace(RELATED_BLOCK_PATTERN, "")
-    .replace(HTML_COMMENT_PATTERN, "")
-    .replace(FENCED_CODE_PATTERN, "")
+    .replace(FENCED_OR_COMMENT_PATTERN, "")
     .replace(IMAGE_LINK_PATTERN, "");
   const links: string[] = [];
   for (const match of searchable.matchAll(OBSIDIAN_LINK_PATTERN)) {
