graphmark 0.3.3__tar.gz → 0.3.4__tar.gz

{graphmark-0.3.3 → graphmark-0.3.4}/CHANGELOG.md

@@ -1,6 +1,40 @@
 # CHANGELOG
 
 
+## v0.3.4 (2026-07-25)
+
+### Bug Fixes
+
+- **graph**: Links to existing out-of-scope notes are not broken (#107)
+  ([#108](https://github.com/cdcoonce/graphmark/pull/108),
+  [`9e386f6`](https://github.com/cdcoonce/graphmark/commit/9e386f6df700b1d866b7d50854b0cc8734a08bf5))
+
+build() dropped unscoped folders, excluded dirs and rules files from the catalog and then forgot
+  they existed, so a link to one failed the resolver and landed in unresolved. The link is correct —
+  Obsidian follows it — it just points somewhere graphmark deliberately does not index, so there was
+  nothing for anyone to fix. On the live vault that was 11 of 155 reported breaks: 8 [[CLAUDE]], 1
+  [[AGENTS]], 2 into templates/.
+
+The same rglob that builds the catalog now records what it skipped, so no extra I/O buys the ability
+  to tell "exists but out of scope" apart from "exists nowhere". Consulted only AFTER the resolver
+  fails — mirroring _targets_non_note_file — so an in-graph note always wins over an out-of-scope
+  namesake and keeps its edge. Any candidate suppresses: out-of-scope notes are never link targets,
+  so ambiguity among them says nothing about whether the in-graph link is broken.
+
+Alias/anchor/.md stripping moved into a shared _strip_display so the resolver and the new check
+  cannot drift on what a display names. That refactor also strips surrounding whitespace, which the
+  resolver did not: 13 column-aligned links of the form [[folder/note | alias]] were reported broken
+  while pointing at real notes, and now resolve into edges (3570 → 3583 on the live vault). Covered
+  by its own test class.
+
+Fixtures are untouched: only the unresolved path changes shape, no expected.json carries an
+  unresolved key, and edges only grow via the whitespace fix. uv.lock catches up to the 0.3.3
+  release bump.
+
+Live vault: 155 → 130 unresolved (12 suppressed, 13 resolved), no genuine break lost — verified by
+  diffing the full before/after sets.
+
+
 ## v0.3.3 (2026-07-25)
 
 ### Bug Fixes

{graphmark-0.3.3 → graphmark-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.3.3
+Version: 0.3.4
 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.3 → graphmark-0.3.4}/pyproject.toml

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

{graphmark-0.3.3 → graphmark-0.3.4}/src/graphmark/graph.py

@@ -25,6 +25,19 @@ def _normalize(text: str) -> str:
 _FILE_SUFFIX_RE = re.compile(r"\.[A-Za-z0-9]{1,10}$")
 
 
+def _strip_display(display: str) -> str:
+    """Reduce a raw wikilink display to its note part: no alias, no anchor, no ``.md``.
+
+    Obsidian treats ``[[Note]]``, ``[[Note|alias]]``, ``[[Note#Section]]`` and ``[[Note.md]]`` as
+    the same link, so every place that asks "which note does this display name?" must strip the
+    same three things. Shared by the resolver and the out-of-scope check so they cannot drift.
+    """
+    target = display.split("|")[0].split("#")[0].strip()
+    if target.lower().endswith(".md"):
+        target = target[: -len(".md")]
+    return target
+
+
 def _targets_non_note_file(display: str) -> bool:
     """True for a link to a file graphmark does not index, e.g. ``[[Board.canvas]]``.
 
@@ -40,6 +53,28 @@ def _targets_non_note_file(display: str) -> bool:
     return bool(match) and match.group(0).lower() != ".md"
 
 
+def _targets_out_of_scope_note(display: str, out_of_scope: dict[str, list[str]]) -> bool:
+    """True for a link to a markdown note that exists but is outside the configured scope.
+
+    ``build`` drops unscoped folders, excluded dirs and rules files from the catalog, so links to
+    them fail the resolver — yet the link is correct, Obsidian follows it, and there is nothing for
+    anyone to fix. Reporting it as broken just fills the vault-health count with noise.
+
+    Only ever consulted after the resolver has already failed, so an in-graph note always wins over
+    an out-of-scope namesake. **Any** candidate suppresses: out-of-scope notes are never link
+    targets, so ambiguity among them says nothing about whether the in-graph link is broken.
+    """
+    target = _strip_display(display)
+    if not target:
+        return False
+    if "/" in target:
+        suffix = target.lower() + ".md"
+        return any(
+            path.lower().endswith(suffix) for paths in out_of_scope.values() for path in paths
+        )
+    return _normalize(target) in out_of_scope
+
+
 def _is_intra_note_reference(display: str) -> bool:
     """True for a link that targets no note, e.g. ``[[#Heading]]`` or ``[[#^block]]``.
 
@@ -80,15 +115,10 @@ class NormalizeResolver:
         return self._flat_cache
 
     def resolve(self, display: str, catalog: dict[str, list[str]]) -> str | None:
-        # Strip alias: "Note|alias" → "Note"
-        display = display.split("|")[0]
-        # Strip anchor: "Note#Section" → "Note"
-        display = display.split("#")[0]
-        # Obsidian accepts an explicit extension, so "Note.md" is the same link as "Note".
-        # Stripped before both branches below: the path-suffix branch appends ".md" itself,
-        # and the bare branch would otherwise normalize to the key "note md".
-        if display.lower().endswith(".md"):
-            display = display[: -len(".md")]
+        # Alias ("Note|alias"), anchor ("Note#Section") and an explicit ".md" extension all name
+        # the same note. Stripped before both branches below: the path-suffix branch appends
+        # ".md" itself, and the bare branch would otherwise normalize to the key "note md".
+        display = _strip_display(display)
 
         if "/" in display:
             # Path-suffix resolution: find unique rel_path ending with "display.md"
@@ -142,13 +172,19 @@ class VaultGraph:
 
         scoped = set(config.scoped_folders)
         md_files: list[Path] = []
+        # Markdown that exists but is out of scope, normalized stem → rel_paths. Collected in
+        # this same walk (no extra I/O) so a link to one can be told apart from a link to a note
+        # that exists nowhere at all.
+        out_of_scope: dict[str, list[str]] = {}
         for path in sorted(root.rglob("*.md")):
-            rel_parts = path.relative_to(root).parts
-            if scoped and rel_parts[0] not in scoped:
-                continue
-            if any(p in excluded for p in rel_parts[:-1]):
-                continue
-            if path.name in rules:
+            rel = path.relative_to(root)
+            rel_parts = rel.parts
+            if (
+                (scoped and rel_parts[0] not in scoped)
+                or any(p in excluded for p in rel_parts[:-1])
+                or path.name in rules
+            ):
+                out_of_scope.setdefault(_normalize(path.stem), []).append(rel.as_posix())
                 continue
             md_files.append(path)
 
@@ -167,7 +203,9 @@ class VaultGraph:
                     continue
                 target = resolver.resolve(display, catalog)
                 if target is None:
-                    if _targets_non_note_file(display):
+                    if _targets_non_note_file(display) or _targets_out_of_scope_note(
+                        display, out_of_scope
+                    ):
                         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

{graphmark-0.3.3 → graphmark-0.3.4}/tests/test_unresolved.py

@@ -233,3 +233,106 @@ class TestNonMarkdownTargets:
     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"]}
+
+
+class TestPaddedDisplays:
+    """Whitespace around the note part must not stop a link from resolving.
+
+    Real vaults contain column-aligned tables — ``[[folder/note        | alias]]`` — where the
+    note part carries trailing spaces. Both resolution branches now see the stripped display
+    (13 such links on a live vault were reported broken while pointing at real notes).
+    """
+
+    def test_padded_bare_display_resolves(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[ b  | the alias]].\n")
+        _write(tmp_path, "b.md", "Target.\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["a.md"] == {"b.md"}
+
+    def test_padded_path_qualified_display_resolves(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[docs/b     | the alias]].\n")
+        _write(tmp_path, "docs/b.md", "Target.\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["a.md"] == {"docs/b.md"}
+
+    def test_padded_md_extension_still_strips(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[b.md  | alias]].\n")
+        _write(tmp_path, "b.md", "Target.\n")
+        assert _build(tmp_path).out_links["a.md"] == {"b.md"}
+
+    def test_a_padded_missing_note_is_still_unresolved(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[ Nowhere  | alias]].\n")
+        assert _build(tmp_path).unresolved == {"a.md": [" Nowhere  | alias"]}
+
+
+class TestOutOfScopeNoteTargets:
+    """A link to a note that exists but is out of graph scope is out of scope, not broken.
+
+    build() drops unscoped folders, excluded dirs and rules files from the catalog and then
+    forgets they exist, so links to them fail the resolver. The link is correct — Obsidian
+    follows it — it just points somewhere graphmark deliberately does not index. On a real
+    vault these were 7% of the reported total ([[CLAUDE]], [[AGENTS]], a templates/ note).
+
+    Consulted only AFTER the resolver fails, so nothing that resolves in-graph is affected.
+    """
+
+    def test_link_to_a_rules_file_is_not_unresolved(self, tmp_path):
+        _write(tmp_path, "notes/a.md", "See [[CLAUDE]].\n")
+        _write(tmp_path, "CLAUDE.md", "Rules.\n")
+        graph = _build(tmp_path, rules_files=["CLAUDE.md"])
+        assert graph.unresolved == {}
+        assert graph.out_links["notes/a.md"] == set()
+
+    def test_link_into_an_unscoped_folder_is_not_unresolved(self, tmp_path):
+        _write(tmp_path, "docs/a.md", "See [[Intake Guide]].\n")
+        _write(tmp_path, "templates/Intake Guide.md", "Template.\n")
+        assert _build(tmp_path, scoped_folders=["docs"]).unresolved == {}
+
+    def test_link_into_an_excluded_dir_is_not_unresolved(self, tmp_path):
+        _write(tmp_path, "a.md", "See [[old thing]].\n")
+        _write(tmp_path, "archive/old thing.md", "Archived.\n")
+        assert _build(tmp_path, excluded_dirs=["archive"]).unresolved == {}
+
+    @pytest.mark.parametrize(
+        "display",
+        ["CLAUDE", "claude", "CLAUDE|the rules", "CLAUDE#Non-negotiables", "CLAUDE.md"],
+    )
+    def test_alias_anchor_case_and_md_forms_all_suppress(self, tmp_path, display):
+        _write(tmp_path, "notes/a.md", f"See [[{display}]].\n")
+        _write(tmp_path, "CLAUDE.md", "Rules.\n")
+        assert _build(tmp_path, rules_files=["CLAUDE.md"]).unresolved == {}
+
+    def test_path_qualified_link_to_an_out_of_scope_note_is_not_unresolved(self, tmp_path):
+        _write(tmp_path, "docs/a.md", "See [[templates/data/Intake Guide]].\n")
+        _write(tmp_path, "templates/data/Intake Guide.md", "Template.\n")
+        assert _build(tmp_path, scoped_folders=["docs"]).unresolved == {}
+
+    def test_an_ambiguous_out_of_scope_stem_still_suppresses(self, tmp_path):
+        # Out-of-scope notes are never link targets, so ambiguity among them says nothing
+        # about whether the in-graph link is broken. Any candidate suppresses.
+        _write(tmp_path, "docs/a.md", "See [[shared]].\n")
+        _write(tmp_path, "templates/one/shared.md", "")
+        _write(tmp_path, "templates/two/shared.md", "")
+        assert _build(tmp_path, scoped_folders=["docs"]).unresolved == {}
+
+    def test_a_note_that_exists_nowhere_is_still_unresolved(self, tmp_path):
+        _write(tmp_path, "docs/a.md", "See [[Nowhere]].\n")
+        _write(tmp_path, "templates/Something Else.md", "")
+        assert _build(tmp_path, scoped_folders=["docs"]).unresolved == {"docs/a.md": ["Nowhere"]}
+
+    def test_an_in_scope_note_still_wins_over_an_out_of_scope_namesake(self, tmp_path):
+        # The rule only applies after the resolver fails, so the real in-graph note wins and
+        # keeps its edge.
+        _write(tmp_path, "docs/a.md", "See [[guide]].\n")
+        _write(tmp_path, "docs/guide.md", "In scope.\n")
+        _write(tmp_path, "templates/guide.md", "Out of scope.\n")
+        graph = _build(tmp_path, scoped_folders=["docs"])
+        assert graph.unresolved == {}
+        assert graph.out_links["docs/a.md"] == {"docs/guide.md"}
+
+    def test_mixed_note_keeps_only_the_real_break(self, tmp_path):
+        _write(tmp_path, "docs/a.md", "[[Intake Guide]] and [[Missing]].\n")
+        _write(tmp_path, "templates/Intake Guide.md", "Template.\n")
+        assert _build(tmp_path, scoped_folders=["docs"]).unresolved == {"docs/a.md": ["Missing"]}