graphmark 0.3.0__tar.gz → 0.3.2__tar.gz

{graphmark-0.3.0 → graphmark-0.3.2}/CHANGELOG.md

@@ -1,6 +1,61 @@
 # CHANGELOG
 
 
+## v0.3.2 (2026-07-25)
+
+### Bug Fixes
+
+- **graph**: Links to non-markdown files are out of scope, not broken
+  ([#102](https://github.com/cdcoonce/graphmark/pull/102),
+  [`0796aa0`](https://github.com/cdcoonce/graphmark/commit/0796aa02d1d582b85a8905fb4b43b72b076bd072))
+
+unresolved reported wikilinks targeting Obsidian Bases, Canvas, images and PDFs as broken. graphmark
+  only indexes *.md, so it has no basis to judge those targets — calling them broken just fills the
+  vault-health count with entries nobody can act on.
+
+Measured on the owner's live vault: 17 of 173 reported breaks (10%) targeted .base/.canvas, and all
+  9 distinct targets exist on disk, in a bases/ directory outside scoped_folders. Every one of those
+  links works in Obsidian.
+
+When the resolver returns None and the target ends in a plausible file extension other than .md,
+  treat it as out of scope: no edge, not counted. The extension test is deliberately strict
+  (trailing dot plus 1-10 alphanumerics) so a title like "v1.2 release notes" is still read as a
+  note. Applying the rule only after the resolver has already failed is what makes it safe — a note
+  that genuinely resolves, such as a real report.v2.md linked as [[report.v2]], never reaches it.
+
+Deliberately no filesystem existence check: it would couple build() to the disk and force
+  enumerating excluded trees like .git. "Out of scope" is the honest report for a file type
+  graphmark does not index.
+
+Closes #101
+
+
+## v0.3.1 (2026-07-25)
+
+### Bug Fixes
+
+- **graph**: Stop counting same-note anchor links as unresolved
+  ([#99](https://github.com/cdcoonce/graphmark/pull/99),
+  [`a1d03f3`](https://github.com/cdcoonce/graphmark/commit/a1d03f3eb0e7b36b6d44d2a4eecfe8bb70da8d11))
+
+unresolved counted anchor-only wikilinks — [[#Heading]], [[#Heading|alias]], [[#^blockref]] — as
+  broken. Those are Obsidian same-note references: they target no note at all, so they are neither
+  an edge nor a broken link. Counting them corrupted the very metric Track D was built around,
+  max_unresolved_links.
+
+Measured on the owner's live 521-note vault: 40 of 213 reported unresolved links (19%) were
+  anchor-only, and the note reported as the worst offender earned that spot purely by navigating
+  itself heavily.
+
+build() now skips a display whose note part (before | and #) is empty. [[Note#Heading]] is
+  unaffected: it still resolves via Note, and still counts as unresolved when Note is missing.
+
+This refines the #75 semantics, which defined ambiguous-counts and self-link-doesn't but never
+  considered anchor-only links.
+
+Closes #98
+
+
 ## v0.3.0 (2026-07-25)
 
 ### Bug Fixes

{graphmark-0.3.0 → graphmark-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.3.0
+Version: 0.3.2
 Summary: Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults.
 Project-URL: Homepage, https://github.com/cdcoonce/graphmark
 Project-URL: Repository, https://github.com/cdcoonce/graphmark

{graphmark-0.3.0 → graphmark-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphmark"
-version = "0.3.0"
+version = "0.3.2"
 description = "Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults."
 readme = "README.md"
 requires-python = ">=3.11"

{graphmark-0.3.0 → graphmark-0.3.2}/src/graphmark/graph.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import string
 from pathlib import Path
 
@@ -18,6 +19,37 @@ def _normalize(text: str) -> str:
     return " ".join(text.lower().translate(_PUNCT_TABLE).split())
 
 
+# A trailing dot plus a short alphanumeric run — a plausible file extension. Deliberately
+# strict so a note title like "v1.2 release notes" (spaces after the dot) is not mistaken
+# for one.
+_FILE_SUFFIX_RE = re.compile(r"\.[A-Za-z0-9]{1,10}$")
+
+
+def _targets_non_note_file(display: str) -> bool:
+    """True for a link to a file graphmark does not index, e.g. ``[[Board.canvas]]``.
+
+    Obsidian wikilinks legitimately target Bases, Canvas, images and PDFs. graphmark only
+    indexes markdown, so it has no basis to call such a link broken — reporting it as
+    unresolved just fills the vault-health count with entries nobody can act on.
+
+    Only ever consulted after the resolver has already failed, so a note that genuinely
+    resolves (say a real ``report.v2.md`` linked as ``[[report.v2]]``) is never suppressed.
+    """
+    target = display.split("|")[0].split("#")[0].strip()
+    match = _FILE_SUFFIX_RE.search(target)
+    return bool(match) and match.group(0).lower() != ".md"
+
+
+def _is_intra_note_reference(display: str) -> bool:
+    """True for a link that targets no note, e.g. ``[[#Heading]]`` or ``[[#^block]]``.
+
+    Obsidian uses an empty note part to mean "somewhere in this same note". Such a link is
+    neither an edge nor a broken link, so it must not be recorded as unresolved — otherwise
+    a note that navigates itself heavily looks like the vault's worst offender.
+    """
+    return not display.split("|")[0].split("#")[0].strip()
+
+
 def build_catalog(docs: list[Document]) -> dict[str, list[str]]:
     """Map normalized stem → list of rel_paths (len > 1 means ambiguous)."""
     catalog: dict[str, list[str]] = {}
@@ -126,8 +158,12 @@ class VaultGraph:
 
         for doc in docs:
             for display in extractor.extract(doc.text):
+                if _is_intra_note_reference(display):
+                    continue
                 target = resolver.resolve(display, catalog)
                 if target is None:
+                    if _targets_non_note_file(display):
+                        continue  # out of scope, not a broken note link
                     # Unresolvable OR ambiguous — the Resolver protocol conflates the two, and
                     # both are equally broken from a vault-health view. Record the raw display
                     # (what a human has to go fix) once per occurrence.

{graphmark-0.3.0 → graphmark-0.3.2}/tests/test_unresolved.py

@@ -130,3 +130,106 @@ class TestUnresolvedIntegration:
         assert isinstance(graph.unresolved, dict)
         # stats is untouched by this addition — the oracle still governs it.
         assert set(stats(graph)) == {"notes", "edges", "orphans", "clusters", "density"}
+
+
+class TestIntraNoteAnchorLinks:
+    """[[#Heading]] is a same-note reference, not a link to another note.
+
+    It is neither an edge nor a broken link, so counting it as unresolved inflates the
+    check gate's max_unresolved_links threshold (measured: 19% of a real vault's total).
+    """
+
+    def test_anchor_only_link_is_not_unresolved(self, tmp_path):
+        _write(tmp_path, "a.md", "# Top\n\nJump to [[#Section]].\n\n## Section\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+
+    def test_anchor_only_link_with_alias_is_not_unresolved(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[#Design cruxes|crux 2]].\n")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_block_reference_is_not_unresolved(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[#^abc123]].\n")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_anchor_only_link_creates_no_edge(self, tmp_path):
+        _write(tmp_path, "a.md", "Jump to [[#Section]].\n")
+        graph = _build(tmp_path)
+        assert graph.out_links["a.md"] == set()
+
+    def test_whitespace_only_display_is_ignored(self, tmp_path):
+        _write(tmp_path, "a.md", "Odd [[   ]] link.\n")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_cross_note_anchor_still_resolves(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[b#Section]].\n")
+        _write(tmp_path, "b.md", "# B\n\n## Section\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["a.md"] == {"b.md"}
+
+    def test_cross_note_anchor_to_a_missing_note_is_still_unresolved(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[Nowhere#Section]].\n")
+        assert _build(tmp_path).unresolved == {"a.md": ["Nowhere#Section"]}
+
+    def test_mixed_note_keeps_only_the_real_break(self, tmp_path):
+        _write(tmp_path, "a.md", "[[#Local]] and [[Missing]] and [[#Other|x]].\n")
+        assert _build(tmp_path).unresolved == {"a.md": ["Missing"]}
+
+
+class TestNonMarkdownTargets:
+    """A link to a file graphmark does not index is out of scope, not broken.
+
+    Obsidian wikilinks legitimately target Bases (.base), Canvas (.canvas), images and PDFs.
+    graphmark only indexes *.md, so it has no basis to call those links broken — on a real
+    vault they were 10% of the reported total, every one of them a working link.
+    """
+
+    @pytest.mark.parametrize(
+        "display",
+        [
+            "Stale Side-Projects.base",
+            "Board.canvas",
+            "diagram.png",
+            "spec.pdf",
+            "sketch.excalidraw",
+            "People Missing Context.base|People Missing Context",
+            "Board.canvas#Section",
+        ],
+    )
+    def test_non_markdown_target_is_not_unresolved(self, tmp_path, display):
+        _write(tmp_path, "a.md", f"See [[{display}]].\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["a.md"] == set()
+
+    def test_md_targets_are_exempt_from_the_rule(self, tmp_path):
+        # .md is explicitly excluded from the non-note rule, so a link ending in .md keeps
+        # whatever the resolver decides. graphmark does not currently resolve a trailing
+        # ".md" (an Obsidian-compatibility gap tracked separately) — the point here is only
+        # that this rule does not silently swallow it.
+        _write(tmp_path, "a.md", "See [[b.md]].\n")
+        _write(tmp_path, "b.md", "Target.\n")
+        assert _build(tmp_path).unresolved == {"a.md": ["b.md"]}
+
+    def test_missing_md_target_is_still_unresolved(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[Nowhere.md]].\n")
+        assert _build(tmp_path).unresolved == {"a.md": ["Nowhere.md"]}
+
+    def test_dotted_title_is_not_mistaken_for_a_file_extension(self, tmp_path):
+        # "v1.2 release notes" has spaces after the dot — it is a note title, so a missing
+        # one must still be reported.
+        _write(tmp_path, "a.md", "See [[v1.2 release notes]].\n")
+        assert _build(tmp_path).unresolved == {"a.md": ["v1.2 release notes"]}
+
+    def test_a_resolvable_dotted_note_is_never_suppressed(self, tmp_path):
+        # The rule only applies after the resolver fails, so a real note wins.
+        _write(tmp_path, "a.md", "See [[report.v2]].\n")
+        _write(tmp_path, "report.v2.md", "Target.\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["a.md"] == {"report.v2.md"}
+
+    def test_mixed_note_keeps_only_the_missing_note(self, tmp_path):
+        _write(tmp_path, "a.md", "[[Chart.base]] and [[Missing]] and [[#local]].\n")
+        assert _build(tmp_path).unresolved == {"a.md": ["Missing"]}