fix(lint): don't hide same-stem orphans behind qualified links (#147)

find_orphans added the bare stem of *every* wikilink to the "incoming" set, so
a qualified link like `[[concepts/foo]]` also registered the stem `foo`. Any
other page that merely shared that stem in a different directory (e.g.
`summaries/foo`) was then treated as linked and excluded from orphan
detection — a genuine orphan was silently missed.

Only add the bare stem when the link itself is a bare stem (no `/`); qualified
links register only their full path. Bare `[[foo]]` links still resolve by
stem, so a page named `foo` in any directory remains non-orphaned.

Adds regression tests for both the qualified-link (orphan now flagged) and
bare-link (still matched) cases.

Author: jichaowang02-lang

openkb/lint.py

@@ -321,10 +321,14 @@ def find_orphans(wiki: Path) -> list[str]:
     incoming: set[str] = set()
     for links in outgoing.values():
         for lnk in links:
-            incoming.add(lnk.strip().strip("/"))
-        # Also add stems
-        for lnk in links:
-            incoming.add(Path(lnk.strip()).stem)
+            cleaned = lnk.strip().strip("/")
+            incoming.add(cleaned)
+            # Only treat a link as a bare-stem reference when it is itself a
+            # bare stem. A qualified link like ``concepts/foo`` must not mark a
+            # same-stem page in another directory (``summaries/foo``) as linked,
+            # which would hide a genuine orphan.
+            if "/" not in cleaned:
+                incoming.add(Path(cleaned).stem)
 
     orphans: list[str] = []
     for rel, links in outgoing.items():

tests/test_lint.py

@@ -114,6 +114,35 @@ def test_empty_wiki_has_no_orphans(self, tmp_path):
 
         assert result == []
 
+    def test_qualified_link_does_not_hide_same_stem_orphan(self, tmp_path):
+        # A qualified link [[concepts/dup]] must not mark a *different* page
+        # that merely shares the "dup" stem (summaries/dup) as linked — that
+        # page is a genuine orphan and must still be flagged.
+        wiki = _make_wiki(tmp_path)
+        (wiki / "concepts" / "dup.md").write_text("# Linked concept", encoding="utf-8")
+        (wiki / "summaries" / "linker.md").write_text(
+            "See [[concepts/dup]]", encoding="utf-8"
+        )
+        (wiki / "summaries" / "dup.md").write_text(
+            "Orphan sharing the 'dup' stem, with no links.", encoding="utf-8"
+        )
+
+        result = find_orphans(wiki)
+
+        assert "summaries/dup" in result
+        assert "concepts/dup" not in result
+
+    def test_bare_stem_link_still_matches_same_stem_page(self, tmp_path):
+        # A bare [[dup]] link (no path) intentionally resolves by stem, so a
+        # page with that stem is not considered an orphan.
+        wiki = _make_wiki(tmp_path)
+        (wiki / "concepts" / "dup.md").write_text("# A concept", encoding="utf-8")
+        (wiki / "summaries" / "linker.md").write_text("See [[dup]]", encoding="utf-8")
+
+        result = find_orphans(wiki)
+
+        assert "concepts/dup" not in result
+
 
 class TestFindMissingEntries:
     def test_no_missing_entries(self, tmp_path):