fix(lint): preserve Obsidian heading, block, and embed link syntax

The single-capture wikilink regex treated [[page#Heading]],
[[page#^block]], ![[file.png]] and [[report.pdf]] as whole page
targets. None of them can ever match a known target, so lint --fix
(strip_ghost_wikilinks) demoted valid Obsidian links to plain text —
silently destroying hand-written notes in explorations/ on a full
sweep — and find_broken_links reported them all as broken.

- Parse the embed marker, target, fragment and alias as named groups.
- Validate only the page target; fragments survive fuzzy canonical
  rewrites ([[concepts/Gist_Memory#Notes]] -> [[concepts/gist-memory#Notes]]).
- Pass through attachment embeds/links (extension whitelist) and
  same-page [[#Heading]] links untouched.
- Treat note embeds ![[concepts/x]] as regular page links: validated,
  rewritten keeping the embed marker, counted as incoming links for
  orphan detection and as graph edges in visualize.

Adds regression coverage including a hand-written explorations/ note
that must survive a wiki-wide lint --fix byte-for-byte.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Aldominguez12

openkb/lint.py

@@ -20,8 +20,42 @@
 from openkb.locks import atomic_write_text
 from openkb.schema import PAGE_CONTENT_DIRS
 
-# Matches [[wikilink]] or [[subdir/link]]
-_WIKILINK_RE = re.compile(r"\[\[([^\]]+)\]\]")
+# Matches [[target]], [[target|alias]], [[target#Heading]], [[target#^block]],
+# same-page fragment links [[#Heading]], and embeds ![[file]]. Named groups
+# keep the pieces separable so Obsidian fragment/embed syntax survives
+# validation and rewriting instead of being demoted to plain text.
+_WIKILINK_RE = re.compile(
+    r"(?P<embed>!)?\[\[(?P<target>[^\]|#]*)(?P<frag>#[^\]|]*)?(?:\|(?P<alias>[^\]]+))?\]\]"
+)
+
+# Non-page link targets ([[report.pdf]], ![[figure.png]]): Obsidian resolves
+# these to vault attachments, so they are never validated against wiki pages.
+_ATTACHMENT_SUFFIXES = {
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".svg",
+    ".pdf",
+    ".mp3",
+    ".mp4",
+    ".wav",
+    ".webm",
+    ".csv",
+    ".json",
+    ".xlsx",
+    ".docx",
+    ".pptx",
+    ".zip",
+}
+
+
+def _is_attachment(target: str) -> bool:
+    """True when a wikilink target points at a file attachment, not a page."""
+    return Path(target).suffix.lower() in _ATTACHMENT_SUFFIXES
+
 
 # Files to exclude from lint scanning (schema, logs, etc.)
 _EXCLUDED_FILES = {"AGENTS.md", "SCHEMA.md", "log.md"}
@@ -68,15 +102,23 @@ def strip_ghost_wikilinks(
 ) -> tuple[str, list[str]]:
     """Strip [[wikilinks]] whose targets do not exist in ``known_targets``.
 
-    For each ``[[X]]`` or ``[[X|alias]]`` in ``content``:
+    For each ``[[X]]``, ``[[X|alias]]``, ``[[X#frag]]``, or
+    ``[[X#frag|alias]]`` in ``content``:
 
     - If ``X`` is in ``known_targets`` exactly, the link is kept as-is.
     - Otherwise, ``X`` is normalized (see :func:`_normalize_target`) and
       matched against the normalized form of each known target. On a hit,
-      the link is rewritten to the canonical target form.
+      the link is rewritten to the canonical target form, preserving any
+      ``#Heading`` / ``#^block`` fragment and alias.
     - Otherwise, the brackets are removed and the link becomes plain text
       (the alias if provided, otherwise the slug rendered as words).
 
+    Obsidian syntax that never targets a wiki page is passed through
+    untouched: attachment embeds and links (``![[file.png]]``,
+    ``[[report.pdf]]``) and same-page fragment links (``[[#Heading]]``).
+    Note embeds (``![[concepts/attention]]``) target pages like any other
+    link and go through the same validation, keeping the ``!`` on rewrite.
+
     Args:
         content: Markdown text containing zero or more ``[[wikilinks]]``.
         known_targets: Valid link targets, e.g.
@@ -96,25 +138,29 @@ def strip_ghost_wikilinks(
     ghosts: list[str] = []
 
     def _repl(m: re.Match) -> str:
-        raw = m.group(1)
-        if "|" in raw:
-            target, alias = raw.split("|", 1)
-            target = target.strip()
-            alias = alias.strip()
-        else:
-            target = raw.strip()
-            alias = None
+        embed = m.group("embed") or ""
+        target = (m.group("target") or "").strip()
+        frag = m.group("frag") or ""
+        alias = (m.group("alias") or "").strip() or None
+
+        # [[#Heading]] links within the same page carry no target to check;
+        # attachment embeds/links (![[fig.png]], [[report.pdf]]) resolve to
+        # vault files, not pages. Note embeds (![[concepts/x]]) fall through
+        # and are validated like any page link.
+        if not target or _is_attachment(target):
+            return m.group(0)
 
         # Direct hit
         if target in known_targets:
             return m.group(0)
 
-        # Fuzzy normalized hit → rewrite to canonical
+        # Fuzzy normalized hit → rewrite to canonical, keeping the
+        # fragment and the embed marker
         canonical = norm_index.get(_normalize_target(target))
         if canonical is not None:
             if alias:
-                return f"[[{canonical}|{alias}]]"
-            return f"[[{canonical}]]"
+                return f"{embed}[[{canonical}{frag}|{alias}]]"
+            return f"{embed}[[{canonical}{frag}]]"
 
         # Ghost — strip brackets, leave readable display
         ghosts.append(target)
@@ -152,12 +198,22 @@ def _all_wiki_pages(wiki: Path) -> dict[str, Path]:
 
 
 def _extract_wikilinks(text: str) -> list[str]:
-    """Return all wikilink targets found in *text*.
-
-    Handles ``[[target|display text]]`` alias syntax — only the target is returned.
+    """Return all page-link targets found in *text*.
+
+    Aliases and ``#Heading`` / ``#^block`` fragments are dropped — only the
+    page part is returned. Note embeds (``![[concepts/x]]``) count as page
+    links; attachment embeds/links (``![[fig.png]]``, ``[[report.pdf]]``)
+    and same-page fragment links (``[[#Heading]]``) are skipped — they
+    never target a wiki page, so reporting them as broken would be a
+    false positive.
     """
-    raw = _WIKILINK_RE.findall(text)
-    return [link.split("|")[0].strip() for link in raw]
+    targets: list[str] = []
+    for m in _WIKILINK_RE.finditer(text):
+        target = (m.group("target") or "").strip()
+        if not target or _is_attachment(target):
+            continue
+        targets.append(target)
+    return targets
 
 
 def list_existing_wiki_targets(wiki_dir: Path) -> set[str]:

tests/test_lint.py

@@ -545,6 +545,193 @@ def test_accepts_prebuilt_norm_index_with_identical_result(self):
         assert "[[concepts/missing]]" not in out_b
 
 
+class TestObsidianSyntax:
+    """Obsidian link syntax beyond ``[[page]]`` / ``[[page|alias]]``.
+
+    Heading links (``[[page#H]]``), block refs (``[[page#^b]]``), same-page
+    fragments (``[[#H]]``), embeds (``![[file.png]]``), and attachment
+    links (``[[file.pdf]]``) are all valid in Obsidian. The linter must
+    neither demote them to plain text (strip/fix) nor report them as
+    broken (find_broken_links).
+    """
+
+    # --- strip_ghost_wikilinks -------------------------------------------
+
+    def test_keeps_heading_fragment_on_direct_match(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "See [[concepts/attention#Scaled Dot-Product]].",
+            {"concepts/attention"},
+        )
+        assert out == "See [[concepts/attention#Scaled Dot-Product]]."
+        assert ghosts == []
+
+    def test_keeps_block_ref_on_direct_match(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "See [[concepts/attention#^abc123]].",
+            {"concepts/attention"},
+        )
+        assert out == "See [[concepts/attention#^abc123]]."
+        assert ghosts == []
+
+    def test_keeps_fragment_with_alias(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "See [[concepts/attention#Scores|the scores]].",
+            {"concepts/attention"},
+        )
+        assert out == "See [[concepts/attention#Scores|the scores]]."
+        assert ghosts == []
+
+    def test_preserves_fragment_through_fuzzy_rewrite(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "See [[concepts/gist_memory#Notes]].",
+            {"concepts/gist-memory"},
+        )
+        assert out == "See [[concepts/gist-memory#Notes]]."
+        assert ghosts == []
+
+    def test_preserves_fragment_and_alias_through_fuzzy_rewrite(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "See [[concepts/gist_memory#Notes|notes]].",
+            {"concepts/gist-memory"},
+        )
+        assert out == "See [[concepts/gist-memory#Notes|notes]]."
+        assert ghosts == []
+
+    def test_ghost_with_fragment_demoted_without_fragment_text(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "See [[concepts/missing#Section]].",
+            {"concepts/attention"},
+        )
+        assert out == "See missing."
+        assert ghosts == ["concepts/missing"]
+
+    def test_attachment_embed_left_untouched(self):
+        text = "Figure: ![[images/doc/p1_img1.png]] here."
+        out, ghosts = strip_ghost_wikilinks(text, set())
+        assert out == text
+        assert ghosts == []
+
+    def test_note_embed_kept_on_direct_match(self):
+        # ![[page]] embeds a note — a page link like any other, keep the "!".
+        out, ghosts = strip_ghost_wikilinks(
+            "Embedded: ![[concepts/attention]].",
+            {"concepts/attention"},
+        )
+        assert out == "Embedded: ![[concepts/attention]]."
+        assert ghosts == []
+
+    def test_note_embed_fuzzy_rewrite_preserves_embed_marker(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "Embedded: ![[concepts/Gist_Memory#Notes]].",
+            {"concepts/gist-memory"},
+        )
+        assert out == "Embedded: ![[concepts/gist-memory#Notes]]."
+        assert ghosts == []
+
+    def test_ghost_note_embed_demoted_without_bang_residue(self):
+        out, ghosts = strip_ghost_wikilinks(
+            "Embedded: ![[concepts/missing]].",
+            {"concepts/attention"},
+        )
+        assert out == "Embedded: missing."
+        assert ghosts == ["concepts/missing"]
+
+    def test_attachment_link_left_untouched(self):
+        text = "Original: [[report.pdf]]."
+        out, ghosts = strip_ghost_wikilinks(text, set())
+        assert out == text
+        assert ghosts == []
+
+    def test_same_page_fragment_left_untouched(self):
+        text = "Jump to [[#Conclusiones]]."
+        out, ghosts = strip_ghost_wikilinks(text, set())
+        assert out == text
+        assert ghosts == []
+
+    # --- find_broken_links ------------------------------------------------
+
+    def test_heading_link_to_existing_page_not_broken(self, tmp_path):
+        wiki = _make_wiki(tmp_path)
+        (wiki / "concepts" / "attention.md").write_text("# Attention", encoding="utf-8")
+        (wiki / "summaries" / "paper.md").write_text(
+            "See [[concepts/attention#Scores]] and [[concepts/attention#^b1]].",
+            encoding="utf-8",
+        )
+
+        assert find_broken_links(wiki) == []
+
+    def test_embed_and_attachment_links_not_reported_broken(self, tmp_path):
+        wiki = _make_wiki(tmp_path)
+        (wiki / "summaries" / "paper.md").write_text(
+            "![[images/doc/fig.png]] and [[scan.pdf]] and [[#Local]].",
+            encoding="utf-8",
+        )
+
+        assert find_broken_links(wiki) == []
+
+    def test_heading_link_to_missing_page_still_broken(self, tmp_path):
+        wiki = _make_wiki(tmp_path)
+        (wiki / "summaries" / "paper.md").write_text(
+            "See [[concepts/ghost#Section]].", encoding="utf-8"
+        )
+
+        result = find_broken_links(wiki)
+
+        assert len(result) == 1
+        assert "ghost" in result[0]
+
+    def test_note_embed_validated_as_page_link(self, tmp_path):
+        # ![[page]] note embeds participate in lint: a broken one is
+        # reported, an existing one is not.
+        wiki = _make_wiki(tmp_path)
+        (wiki / "concepts" / "attention.md").write_text("# Attention", encoding="utf-8")
+        (wiki / "summaries" / "paper.md").write_text(
+            "![[concepts/attention]] and ![[concepts/ghost]].", encoding="utf-8"
+        )
+
+        result = find_broken_links(wiki)
+
+        assert len(result) == 1
+        assert "ghost" in result[0]
+
+    def test_note_embed_counts_as_incoming_link_for_orphans(self, tmp_path):
+        # A page referenced only via ![[embed]] is linked, not an orphan.
+        wiki = _make_wiki(tmp_path)
+        (wiki / "concepts" / "embedded.md").write_text("# Embedded", encoding="utf-8")
+        (wiki / "summaries" / "host.md").write_text("![[concepts/embedded]]", encoding="utf-8")
+
+        result = find_orphans(wiki)
+
+        assert "concepts/embedded" not in result
+
+    # --- fix_broken_links regression on explorations/ ---------------------
+
+    def test_fix_is_idempotent_on_handwritten_exploration(self, tmp_path):
+        """A manually written note in explorations/ using the full Obsidian
+        syntax must survive a wiki-wide ``lint --fix`` sweep unchanged —
+        this was the data-loss path: heading/block/embed links were being
+        demoted to plain text."""
+        wiki = _make_wiki(tmp_path)
+        (wiki / "concepts" / "attention.md").write_text("# Attention", encoding="utf-8")
+        (wiki / "explorations").mkdir()
+        note = wiki / "explorations" / "notas-manuales.md"
+        original = (
+            "# Notas\n\n"
+            "Ver [[concepts/attention#Scaled Dot-Product]] y "
+            "[[concepts/attention#^bloque1|el bloque]].\n\n"
+            "![[images/doc/p1_img1.png]]\n\n"
+            "Nota embebida: ![[concepts/attention]]\n\n"
+            "Adjunto: [[informe.pdf]] — y volver a [[#Notas]].\n"
+        )
+        note.write_text(original, encoding="utf-8")
+
+        files_changed, ghosts = fix_broken_links(wiki)
+
+        assert note.read_text(encoding="utf-8") == original
+        assert files_changed == 0
+        assert ghosts == 0
+
+
 class TestBuildNormIndex:
     def test_returns_normalized_to_canonical_map(self):
         idx = build_norm_index({"concepts/Gist_Memory", "summaries/Paper"})