graphmark 0.8.1__tar.gz → 0.9.0__tar.gz

{graphmark-0.8.1 → graphmark-0.9.0}/CHANGELOG.md

@@ -1,6 +1,61 @@
 # CHANGELOG
 
 
+## v0.9.0 (2026-07-26)
+
+### Bug Fixes
+
+- **graph**: Normalize path-qualified links component-wise (#146)
+  ([#162](https://github.com/cdcoonce/graphmark/pull/162),
+  [`a6cc158`](https://github.com/cdcoonce/graphmark/commit/a6cc1587cdbcf28a6b5360e2bec627a8df8f20c1))
+
+Bare resolution went through `_normalize` — NFC, lowercase, punctuation and symbols folded — while
+  path resolution went through `_fold_case`, which folds only case and Unicode form. So `[[Q1 -
+  Review]]` found `Q1 — Review.md` but `[[notes/Q1 - Review]]` did not: the same title reachable or
+  not depending on whether the writer happened to qualify the link with a folder.
+
+Both branches now compare **path components**, each through the one normalizer: the display's
+  components must be a suffix of the candidate's. That subsumes #136's boundary rule rather than
+  restating it — a suffix over lists cannot match mid-component — while letting every punctuation
+  equivalence `_normalize` already absorbs work in both branches.
+
+The trap: `/` is structural. `[[a/b]]` must never reach `a-b.md`, even though `a/b` and `a-b`
+  normalize alike once a separator is folded. Components are normalized individually and the
+  separator is never one of them. Tested in both directions, and those tests passed BEFORE the
+  change — they are the guard, not the feature.
+
+The index now buckets by normalized final component and caches each path's components, so
+  per-component normalization runs once per note rather than once per link.
+
+Reference vault A/B'd on one snapshot: byte-identical (6230 resolved, 3725 edges, 0 unresolved).
+  blue-book markdown counts identical; build 267 -> 393 ms, still 7x better than the 2718 ms this
+  session started from.
+
+### Features
+
+- **graph**: Add the markdown-autolinks dialect (#156)
+  ([#163](https://github.com/cdcoonce/graphmark/pull/163),
+  [`5ccf527`](https://github.com/cdcoonce/graphmark/commit/5ccf527576037915bd12485d205f2c7bf63b1c7f))
+
+A markdown link is a relative path, but the widely-used mkdocs-autolinks plugin resolves a BARE
+  filename anywhere in the tree. blue-book runs it: 5.8% of its links resolve strictly, 92.7% by
+  name, 1.5% by neither.
+
+Added as an explicit fourth `link_syntax` value, NOT a fallback. Trying a second rule when the first
+  fails is the shape of #136 — a quiet extra rule producing an edge to a note the link does not name
+  — and the 1.5% that match neither dialect show a fallback would not even have been complete. The
+  vault owner states which renderer they use, exactly as they already state their scope.
+
+Only BARE targets take the plugin's rule; a target containing "/" keeps the relative rule in this
+  mode too, so a wrong qualified path is never rescued by a filename match elsewhere. Bare names go
+  through the existing catalog lookup, so ambiguity is refused exactly as it always was — no dialect
+  may invent a resolution.
+
+blue-book, markdown -> markdown-autolinks: resolved 591 (5.8%) -> 10,001 (98.5%), edges 430 -> 4878,
+  orphans 790 -> 106, ambiguous 0, missing 9558 -> 148. Also faster (356 -> 234 ms): a bare name
+  hits the catalog dict instead of the path index.
+
+
 ## v0.8.1 (2026-07-26)
 
 ### Performance Improvements

{graphmark-0.8.1 → graphmark-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.8.1
+Version: 0.9.0
 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
@@ -119,7 +119,7 @@ graph, so set `link_syntax`:
 
 ```toml
 root = "."
-link_syntax = "both"   # "wikilink" (default) | "markdown" | "both"
+link_syntax = "both"   # "wikilink" (default) | "markdown" | "both" | "markdown-autolinks"
 ```
 
 The two resolve differently, and the difference is not cosmetic:
@@ -129,6 +129,12 @@ The two resolve differently, and the difference is not cosmetic:
 - a **markdown** link is a path **relative to the linking note** — `[x](../other/b.md)` means that
   file and nothing else, so the same filename in two folders is not ambiguous at all.
 
+`markdown-autolinks` is `markdown` with the [mkdocs-autolinks](https://github.com/zachhannum/mkdocs-autolinks-plugin)
+plugin's rule for **bare** targets: `[tdd](tdd.md)` names a note anywhere in the tree, not a sibling
+file. Set it only if your site actually runs that plugin — it is never applied as a fallback, because
+a second rule tried after the first fails is how a link ends up pointing at a note it does not name.
+A target that contains `/` keeps the relative rule in this mode too.
+
 If your links are in a syntax graphmark is not reading, it says so on stderr rather than reporting a
 confidently empty graph:
 

{graphmark-0.8.1 → graphmark-0.9.0}/README.md

@@ -91,7 +91,7 @@ graph, so set `link_syntax`:
 
 ```toml
 root = "."
-link_syntax = "both"   # "wikilink" (default) | "markdown" | "both"
+link_syntax = "both"   # "wikilink" (default) | "markdown" | "both" | "markdown-autolinks"
 ```
 
 The two resolve differently, and the difference is not cosmetic:
@@ -101,6 +101,12 @@ The two resolve differently, and the difference is not cosmetic:
 - a **markdown** link is a path **relative to the linking note** — `[x](../other/b.md)` means that
   file and nothing else, so the same filename in two folders is not ambiguous at all.
 
+`markdown-autolinks` is `markdown` with the [mkdocs-autolinks](https://github.com/zachhannum/mkdocs-autolinks-plugin)
+plugin's rule for **bare** targets: `[tdd](tdd.md)` names a note anywhere in the tree, not a sibling
+file. Set it only if your site actually runs that plugin — it is never applied as a fallback, because
+a second rule tried after the first fails is how a link ends up pointing at a note it does not name.
+A target that contains `/` keeps the relative rule in this mode too.
+
 If your links are in a syntax graphmark is not reading, it says so on stderr rather than reporting a
 confidently empty graph:
 

{graphmark-0.8.1 → graphmark-0.9.0}/docs/ROADMAP.md

@@ -243,7 +243,7 @@ Evaluated against the ecosystem and dropped for zero consumer pull; do not re-li
   10,149 of them and zero extracted edges. Config-gated (`link_syntax`), default unchanged,
   `Resolver` untouched. Note what it did *not* do: blue-book resolves 5.8% by strict relative path
   and 92.7% by basename-anywhere (it runs `mkdocs-autolinks`), and no fallback was slipped in —
-  silently trying a second rule when the first fails is the shape of #136. The dialect is #156.
+  silently trying a second rule when the first fails is the shape of #136. The dialect shipped too (#156), as an explicit fourth value rather than a fallback: blue-book goes from 5.8% to **98.5%** resolved, 430 to 4878 edges, 790 to 106 orphans, with ambiguity still refused at 0.
 - Re-platforming (no swapping networkx; no async/parallel rewrites).
 - Performance work without a benchmark showing pain (the live consumer is a ~340-note vault). The
   known ceilings — O(L·N) path-suffix resolution, O(A·(V+E)) `siloed_notes`, per-metric graph

{graphmark-0.8.1 → graphmark-0.9.0}/pyproject.toml

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

{graphmark-0.8.1 → graphmark-0.9.0}/src/graphmark/config.py

@@ -13,7 +13,7 @@ from pathlib import Path
 
 #: Every value ``VaultConfig.link_syntax`` accepts. A consumer may switch on these, so the set is
 #: part of the config contract.
-LINK_SYNTAXES = frozenset({"wikilink", "markdown", "both"})
+LINK_SYNTAXES = frozenset({"wikilink", "markdown", "both", "markdown-autolinks"})
 
 
 @dataclass(frozen=True)
@@ -55,7 +55,10 @@ class VaultConfig:
     #: what every frozen fixture encodes, so the default keeps existing behavior byte-identical.
     #: ``"markdown"`` reads ``[text](note.md)``, the syntax non-Obsidian markdown vaults use — added
     #: on demand after a corpus vault turned out to have 11,198 of them and zero extracted edges.
-    #: ``"both"`` reads each, which is what Obsidian itself accepts.
+    #: ``"both"`` reads each, which is what Obsidian itself accepts. ``"markdown-autolinks"`` is
+    #: ``"markdown"`` with the widely-used mkdocs plugin's rule for **bare** targets: a filename
+    #: with no ``/`` names a note anywhere in the tree rather than a sibling file. Stated by the
+    #: vault owner, never guessed — see the note on ``_resolve_markdown_target``.
     link_syntax: str = "wikilink"
     check: CheckPolicy = field(default_factory=CheckPolicy)
 

{graphmark-0.8.1 → graphmark-0.9.0}/src/graphmark/graph.py

@@ -110,22 +110,36 @@ def _targets_non_note_file(display: str) -> bool:
     return bool(match) and match.group(0).lower() != ".md"
 
 
-def _matches_path_suffix(rel_path: str, suffix: str) -> bool:
-    """True when ``rel_path`` ends with ``suffix`` **on a path-component boundary**.
+def _path_components(name: str) -> tuple[str, ...]:
+    """A path split on ``/``, each component through ``_normalize``, ``.md`` dropped.
+
+    This is what makes path-qualified links normalize like bare ones. They used to fold only case
+    and Unicode form, so ``[[Q1 - Review]]`` found ``Q1 — Review.md`` while
+    ``[[notes/Q1 - Review]]`` did not — the same title reachable or not depending on whether the
+    writer happened to qualify it with a folder.
+
+    Components are normalized **individually** and the separator is never one of them, which is what
+    keeps ``/`` structural: ``[[a/b]]`` yields ``("a", "b")`` and can never reach ``a-b.md``, whose
+    single component is ``"a b"``. That distinction is the whole reason this is a tuple rather than
+    a normalized string.
+
+    A component that normalizes to empty — a trailing slash, or pure punctuation — is kept as
+    ``""``. No real path component ever normalizes to empty, so such a display matches nothing,
+    which is the conservative answer.
+    """
+    name = name[: -len(".md")] if name.lower().endswith(".md") else name
+    return tuple(_normalize(part) for part in name.split("/"))
+
 
-    ``suffix`` is a lowercased ``folder/note.md``. A raw ``str.endswith`` is not enough: it accepts
-    ``homework/Tasks.md`` for ``[[work/Tasks]]``, because nothing requires the character before the
-    match to be a separator. That produced an edge to the wrong note — silently, since the link then
-    counts as ``resolved`` — and, when the real folder also existed, a spurious second match that
-    made the resolver decline a correct link.
+def _names_path(candidate: tuple[str, ...], display: tuple[str, ...]) -> bool:
+    """True when ``display``'s components are a suffix of ``candidate``'s.
 
-    The match is legal only when it consumes the whole rel_path or is preceded by ``/``.
+    Subsumes the boundary rule #136 added: a suffix over *lists* cannot match mid-component, so
+    ``[[work/Tasks]]`` cannot reach ``homework/Tasks.md`` — ``("homework", "tasks")`` does not end
+    with ``("work", "tasks")``. The string-suffix version accepted it, silently producing an edge
+    to the wrong note.
     """
-    lowered = _fold_case(rel_path)
-    if not lowered.endswith(suffix):
-        return False
-    rest = len(lowered) - len(suffix)
-    return rest == 0 or lowered[rest - 1] == "/"
+    return bool(display) and "" not in display and candidate[-len(display) :] == display
 
 
 def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
@@ -143,8 +157,7 @@ def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
     if not target:
         return []
     if "/" in target:
-        suffix = _fold_case(target) + ".md"
-        return sorted(_suffix_matches(suffix, catalog, _CANDIDATE_INDEX))
+        return sorted(_path_matches(target, catalog, _CANDIDATE_INDEX))
     return list(catalog.get(_normalize(target), ()))
 
 
@@ -212,14 +225,21 @@ def build_catalog(docs: list[Document]) -> dict[str, list[str]]:
     return catalog
 
 
+#: A normalized final component → the paths ending with it, each paired with its precomputed
+#: components. Precomputing means the per-component normalization runs once per note, not per link.
+_Buckets = dict[str, list[tuple[str, tuple[str, ...]]]]
+
+
 class _FilenameIndex:
-    """Catalog paths bucketed by folded filename, so a path-qualified link scans a bucket.
+    """Catalog paths bucketed by normalized final component, so a path link scans a bucket.
 
-    A legal suffix match must consume whole path components (see ``_matches_path_suffix``), so a
-    candidate's **last** component always equals the display's last component plus ``.md``.
-    Bucketing by that filename is therefore *exactly* equivalent to scanning every path — same
-    matches, same order — while turning an O(N) sweep into a dict lookup over a bucket that is
-    almost always one entry deep.
+    A match requires the display's components to be a suffix of the candidate's
+    (``_names_path``), so a candidate's **last** component always equals the display's last.
+    Bucketing by it is therefore *exactly* equivalent to scanning every path — same matches, same
+    order — while turning an O(N) sweep into a dict lookup over a bucket almost always one deep.
+
+    Components are cached alongside each path, so the per-component normalization happens once per
+    note rather than once per link.
 
     This mattered little while path-qualified links were rare: most wikilink displays are bare names
     hitting the catalog dict directly, which is why the ``O(L·N)`` ceiling was documented and
@@ -245,17 +265,18 @@ class _FilenameIndex:
 
     def __init__(self) -> None:
         # Insertion-ordered, so the oldest entry is the one evicted.
-        self._slots: dict[int, tuple[dict[str, list[str]], dict[str, list[str]]]] = {}
+        self._slots: dict[int, tuple[dict[str, list[str]], _Buckets]] = {}
 
-    def for_catalog(self, catalog: dict[str, list[str]]) -> dict[str, list[str]]:
+    def for_catalog(self, catalog: dict[str, list[str]]) -> _Buckets:
         cached = self._slots.get(id(catalog))
         if cached is not None and cached[0] is catalog:
             return cached[1]
 
-        buckets: dict[str, list[str]] = {}
+        buckets: _Buckets = {}
         for paths in catalog.values():
             for path in paths:
-                buckets.setdefault(_fold_case(path.rsplit("/", 1)[-1]), []).append(path)
+                components = _path_components(path)
+                buckets.setdefault(components[-1], []).append((path, components))
 
         if len(self._slots) >= self._MAX_SLOTS:
             del self._slots[next(iter(self._slots))]
@@ -263,10 +284,13 @@ class _FilenameIndex:
         return buckets
 
 
-def _suffix_matches(suffix: str, catalog: dict[str, list[str]], index: _FilenameIndex) -> list[str]:
-    """Every rel_path that ``suffix`` (a folded ``folder/note.md``) names, in flatten order."""
-    bucket = index.for_catalog(catalog).get(suffix.rsplit("/", 1)[-1], ())
-    return [path for path in bucket if _matches_path_suffix(path, suffix)]
+def _path_matches(target: str, catalog: dict[str, list[str]], index: _FilenameIndex) -> list[str]:
+    """Every rel_path that a path-qualified ``target`` names, in catalog order."""
+    display = _path_components(target)
+    if not display or "" in display:
+        return []
+    bucket = index.for_catalog(catalog).get(display[-1], ())
+    return [path for path, components in bucket if _names_path(components, display)]
 
 
 #: Shared by ``candidates_for``, which takes a catalog rather than a resolver and so cannot reach
@@ -291,8 +315,7 @@ class NormalizeResolver:
             # Path-suffix resolution: find unique rel_path ending with "display.md". Note that an
             # exact whole-path hit cannot short-circuit — "work/Tasks" names both "work/Tasks.md"
             # and "a/work/Tasks.md", and the honest answer there is to decline.
-            suffix = _fold_case(display) + ".md"
-            matches = _suffix_matches(suffix, catalog, self._index)
+            matches = _path_matches(display, catalog, self._index)
             return matches[0] if len(matches) == 1 else None
 
         # Bare-link resolution: normalize and look up in catalog
@@ -510,8 +533,20 @@ def diagnose(graph: VaultGraph, display: str, *, suggest: int = 0) -> LinkDiagno
     return diagnosis
 
 
-def resolve_relative_target(target: str, source_rel_path: str) -> str | None:
-    """Turn a markdown link's relative target into a vault-relative path, or ``None``.
+def resolve_markdown_target(
+    target: str, source_rel_path: str, *, autolinks: bool = False
+) -> str | None:
+    """Turn a markdown link's target into something the resolver can match, or ``None``.
+
+    With ``autolinks``, a **bare** target — a filename with no ``/`` — is handed through unchanged
+    so the ordinary name-based rule finds it anywhere in the tree. That is the `mkdocs-autolinks`
+    plugin's behavior, and it is **opt-in rather than a fallback**: trying a second rule when the
+    first fails is the shape of #136, where a quiet extra rule produced an edge to a note the link
+    did not name. A target that *is* path-qualified keeps the relative rule even in this mode, so
+    a wrong qualified path is never rescued by a filename match elsewhere.
+
+    Measured on `lyz-code/blue-book`, which runs the plugin: 5.8% of its links resolve strictly,
+    92.7% by name, 1.5% by neither — so a fallback would not even have been complete.
 
     A markdown target is a **path**, not a name: ``[x](../other/b.md)`` means "the file at that
     location relative to me". That is the first resolution rule in this package that depends on
@@ -529,10 +564,13 @@ def resolve_relative_target(target: str, source_rel_path: str) -> str | None:
     is a separate decision, not a fallback to slip in here — silently trying a second rule when the
     first fails is how a link resolves to the wrong note.
 
-    ``None`` for a target that escapes the vault root. That is not an error and not a resolution —
+    Without ``autolinks``, or for any target containing ``/``: ``None`` when the target escapes the
+    vault root. That is not an error and not a resolution —
     a link out of the vault names no note in the graph, so it is reported ``missing`` like any other
     target that is not there.
     """
+    if autolinks and "/" not in target:
+        return target
     combined = PurePosixPath(source_rel_path).parent / target
     normalized = posixpath.normpath(str(combined))
     # normpath leaves leading "..", which is the only way to express "above the root".
@@ -672,14 +710,15 @@ class VaultGraph:
         # pre-processing: a wikilink display is a *name*, a markdown target is a *path relative to
         # the linking note*, and only the latter can be normalized once the source note is known.
         read_wikilinks = config.link_syntax in ("wikilink", "both")
-        read_markdown = config.link_syntax in ("markdown", "both")
+        read_markdown = config.link_syntax in ("markdown", "both", "markdown-autolinks")
+        autolinks = config.link_syntax == "markdown-autolinks"
         md_extractor = MarkdownLinkExtractor() if read_markdown else None
 
         for doc in docs:
             displays = list(extractor.extract(doc.text)) if read_wikilinks else []
             if md_extractor is not None:
                 for target in md_extractor.extract(doc.text):
-                    resolved = resolve_relative_target(target, doc.rel_path)
+                    resolved = resolve_markdown_target(target, doc.rel_path, autolinks=autolinks)
                     # A target above the vault root names no note here. Kept in the stream as the
                     # raw target so it is counted and reported `missing`, never silently dropped —
                     # the conservation law holds for every syntax that is read.

graphmark-0.9.0/tests/test_autolinks.py

@@ -0,0 +1,130 @@
+"""The mkdocs-autolinks dialect: a bare markdown target resolves by name (#156).
+
+A markdown link is a *relative path* — `[tdd](tdd.md)` from `docs/architecture/x.md` means
+`docs/architecture/tdd.md` and nothing else. But the widely-used `mkdocs-autolinks` plugin resolves
+a bare filename **anywhere in the tree**, so the same link reaches `docs/coding/tdd.md`. Measured on
+`lyz-code/blue-book`, which runs that plugin: 5.8% of its links resolve strictly, 92.7% by name.
+
+This is an explicit fourth `link_syntax` value, **not a fallback**. Trying a second rule when the
+first fails is the shape of #136 — a rule that quietly produces an edge to a note the link does not
+name — and the 1.5% that match neither dialect show a fallback would not even be complete. The vault
+owner states which renderer they use, exactly as they already state their scope.
+
+A bare name goes to the *existing* wikilink rule, so ambiguity is refused the same way it
+always was: no dialect may invent a resolution.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph
+from graphmark.parse import WikilinkExtractor
+
+
+def _write(root: Path, rel: str, text: str = "") -> None:
+    path = root / rel
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _build(root: Path, **kw) -> VaultGraph:
+    return VaultGraph.build(VaultConfig(root=root, **kw), WikilinkExtractor(), NormalizeResolver())
+
+
+class TestBareTargetsResolveByName:
+    def test_a_bare_target_reaches_a_note_elsewhere_in_the_tree(self, tmp_path):
+        # blue-book's shape: [tdd](tdd.md) from docs/architecture/ reaching docs/coding/tdd.md.
+        _write(tmp_path, "docs/coding/tdd.md")
+        _write(tmp_path, "docs/architecture/x.md", "[tdd](tdd.md)\n")
+        graph = _build(tmp_path, link_syntax="markdown-autolinks")
+        assert graph.out_links["docs/architecture/x.md"] == {"docs/coding/tdd.md"}
+        assert graph.link_counts["missing"] == 0
+
+    def test_strict_markdown_still_reports_that_link_missing(self, tmp_path):
+        _write(tmp_path, "docs/coding/tdd.md")
+        _write(tmp_path, "docs/architecture/x.md", "[tdd](tdd.md)\n")
+        assert _build(tmp_path, link_syntax="markdown").link_counts["missing"] == 1
+
+    def test_a_sibling_target_still_resolves(self, tmp_path):
+        _write(tmp_path, "docs/b.md")
+        _write(tmp_path, "docs/a.md", "[b](b.md)\n")
+        assert _build(tmp_path, link_syntax="markdown-autolinks").out_links["docs/a.md"] == {
+            "docs/b.md"
+        }
+
+    def test_the_name_normalizes_like_any_other(self, tmp_path):
+        _write(tmp_path, "docs/coding/Q1 — Review.md")
+        _write(tmp_path, "x.md", "[q](Q1%20-%20Review.md)\n")
+        assert _build(tmp_path, link_syntax="markdown-autolinks").unresolved == {}
+
+
+class TestAmbiguityIsStillRefused:
+    def test_a_name_claimed_by_two_notes_is_ambiguous(self, tmp_path):
+        # The rule this dialect must not break: no dialect may invent a resolution.
+        _write(tmp_path, "one/note.md")
+        _write(tmp_path, "two/note.md")
+        _write(tmp_path, "x.md", "[n](note.md)\n")
+        graph = _build(tmp_path, link_syntax="markdown-autolinks")
+        assert graph.link_counts["ambiguous"] == 1
+        assert graph.out_links["x.md"] == set()
+
+    def test_a_name_that_exists_nowhere_is_missing(self, tmp_path):
+        _write(tmp_path, "x.md", "[gone](nowhere.md)\n")
+        assert _build(tmp_path, link_syntax="markdown-autolinks").link_counts["missing"] == 1
+
+
+class TestPathQualifiedTargetsStayRelative:
+    def test_a_target_with_a_slash_uses_the_relative_rule(self, tmp_path):
+        # Only *bare* names get the plugin's behavior; a qualified target still means what it says.
+        _write(tmp_path, "docs/deep/other/b.md")
+        _write(tmp_path, "docs/deep/a.md", "[b](other/b.md)\n")
+        assert _build(tmp_path, link_syntax="markdown-autolinks").out_links["docs/deep/a.md"] == {
+            "docs/deep/other/b.md"
+        }
+
+    def test_a_qualified_target_that_is_wrong_is_not_rescued_by_name(self, tmp_path):
+        # The anti-fallback assertion: "elsewhere/b.md" names no note here, and the fact that a
+        # b.md exists somewhere must NOT rescue it. That rescue is exactly the #136 shape.
+        _write(tmp_path, "docs/coding/b.md")
+        _write(tmp_path, "docs/a.md", "[b](elsewhere/b.md)\n")
+        graph = _build(tmp_path, link_syntax="markdown-autolinks")
+        assert graph.link_counts["missing"] == 1
+        assert graph.out_links["docs/a.md"] == set()
+
+    def test_a_parent_relative_target_still_resolves(self, tmp_path):
+        _write(tmp_path, "docs/other/b.md")
+        _write(tmp_path, "docs/deep/a.md", "[b](../other/b.md)\n")
+        assert _build(tmp_path, link_syntax="markdown-autolinks").out_links["docs/deep/a.md"] == {
+            "docs/other/b.md"
+        }
+
+
+class TestOtherModesUnchanged:
+    def test_wikilinks_are_not_read_in_this_mode(self, tmp_path):
+        _write(tmp_path, "b.md")
+        _write(tmp_path, "a.md", "[[b]]\n")
+        assert _build(tmp_path, link_syntax="markdown-autolinks").out_links["a.md"] == set()
+
+    def test_the_default_is_still_wikilink(self, tmp_path):
+        _write(tmp_path, "b.md")
+        _write(tmp_path, "a.md", "[b](b.md)\n[[b]]\n")
+        graph = _build(tmp_path)
+        assert graph.link_counts["resolved"] == 1
+
+
+class TestConfig:
+    def test_it_is_an_accepted_syntax(self, tmp_path):
+        from graphmark.config import LINK_SYNTAXES
+
+        assert "markdown-autolinks" in LINK_SYNTAXES
+
+    def test_it_loads_from_toml(self, tmp_path):
+        from graphmark.config import load_config
+
+        cfg = tmp_path / "v.toml"
+        cfg.write_text(
+            f'root = "{tmp_path}"\nlink_syntax = "markdown-autolinks"\n', encoding="utf-8"
+        )
+        assert load_config(cfg).link_syntax == "markdown-autolinks"

{graphmark-0.8.1 → graphmark-0.9.0}/tests/test_path_index.py

@@ -31,16 +31,23 @@ def _build(root: Path, **kw) -> VaultGraph:
 
 
 def _scan_resolve(display: str, catalog: dict[str, list[str]]) -> list[str]:
-    """The pre-#157 behavior, written out: compare against every path, in flatten order.
+    """The unindexed behavior, written out: compare against every path, in catalog order.
 
-    Kept as an independent reference rather than by calling the implementation, so the equivalence
-    tests below compare two things instead of one thing with itself.
+    An independent reference rather than a call into the implementation, so the equivalence tests
+    below compare two things instead of one thing with itself. Restated for #146, which made the
+    comparison component-wise: a display names a path when its normalized components are a suffix of
+    the path's.
     """
-    from graphmark.graph import _fold_case, _matches_path_suffix, _strip_display
+    from graphmark.graph import _normalize, _strip_display
 
-    target = _strip_display(display)
-    suffix = _fold_case(target) + ".md"
-    return [p for paths in catalog.values() for p in paths if _matches_path_suffix(p, suffix)]
+    def components(name: str) -> list[str]:
+        name = name[:-3] if name.lower().endswith(".md") else name
+        return [_normalize(part) for part in name.split("/")]
+
+    want = components(_strip_display(display))
+    if not want or "" in want:
+        return []
+    return [p for paths in catalog.values() for p in paths if components(p)[-len(want) :] == want]
 
 
 class TestEquivalence:

graphmark-0.9.0/tests/test_path_normalization.py

@@ -0,0 +1,141 @@
+"""Path-qualified links normalize like bare ones (#146).
+
+Bare resolution went through `_normalize` — NFC, lowercase, punctuation and symbols folded — while
+path resolution went through `_fold_case`, which folds only case and Unicode form. So
+`[[Q1 - Review]]` found `Q1 — Review.md` but `[[notes/Q1 - Review]]` did not: the same title was
+reachable or not depending on whether the writer happened to qualify the link with a folder, which
+is arbitrary from a user's point of view.
+
+The fix compares **path components**, each normalized by the one function: the display's components
+must be a suffix of the candidate's. That subsumes #136's boundary rule for free — a suffix over
+lists cannot match mid-component — while letting every punctuation equivalence `_normalize` already
+absorbs work in both branches.
+
+The trap this must not fall into: `/` is structural. `[[a/b]]` must never reach `a-b.md`, even
+though `a/b` and `a-b` normalize to the same characters once the separator is folded. Components
+are normalized individually and the separator is never one of them, which keeps them apart.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph, candidates_for
+from graphmark.parse import WikilinkExtractor
+
+
+def _write(root: Path, rel: str, text: str = "") -> None:
+    path = root / rel
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _build(root: Path, **kw) -> VaultGraph:
+    return VaultGraph.build(VaultConfig(root=root, **kw), WikilinkExtractor(), NormalizeResolver())
+
+
+class TestSeparatorStaysStructural:
+    """The trap. A `/` is a path boundary, never a character to fold."""
+
+    def test_a_slash_display_does_not_reach_a_hyphen_file(self, tmp_path):
+        _write(tmp_path, "a-b.md")
+        _write(tmp_path, "src.md", "[[a/b]]")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {"src.md": ["a/b"]}
+        assert candidates_for("a/b", graph.catalog) == []
+
+    def test_a_slash_display_does_not_reach_a_space_file(self, tmp_path):
+        _write(tmp_path, "a b.md")
+        _write(tmp_path, "src.md", "[[a/b]]")
+        assert _build(tmp_path).unresolved == {"src.md": ["a/b"]}
+
+    def test_a_hyphen_display_does_not_reach_a_nested_file(self, tmp_path):
+        # The reverse direction: "a-b" is one name, not two components.
+        _write(tmp_path, "a/b.md")
+        _write(tmp_path, "src.md", "[[a-b]]")
+        assert _build(tmp_path).unresolved == {"src.md": ["a-b"]}
+
+
+class TestPunctuationFoldsWithinAComponent:
+    def test_a_path_qualified_em_dash_title(self, tmp_path):
+        _write(tmp_path, "notes/Q1 — Review.md")
+        _write(tmp_path, "src.md", "[[notes/Q1 - Review]]")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["src.md"] == {"notes/Q1 — Review.md"}
+
+    def test_a_path_qualified_hyphen_vs_space(self, tmp_path):
+        _write(tmp_path, "notes/oura pipeline.md")
+        _write(tmp_path, "src.md", "[[notes/oura-pipeline]]")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_the_folder_component_folds_too(self, tmp_path):
+        _write(tmp_path, "my-notes/thing.md")
+        _write(tmp_path, "src.md", "[[my notes/thing]]")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_both_branches_now_agree(self, tmp_path):
+        # The actual defect: the same title, reachable one way and not the other.
+        _write(tmp_path, "notes/Q1 — Review.md")
+        _write(tmp_path, "src.md", "[[Q1 - Review]]\n[[notes/Q1 - Review]]")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.link_counts["resolved"] == 2
+
+
+class TestBoundaryRuleSurvives:
+    """#136's guarantee, now a consequence of comparing component lists."""
+
+    def test_a_longer_folder_name_still_does_not_satisfy_a_shorter_one(self, tmp_path):
+        _write(tmp_path, "homework/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/Tasks]]")
+        assert _build(tmp_path).unresolved == {"src.md": ["work/Tasks"]}
+
+    def test_any_depth_of_prefix_still_resolves(self, tmp_path):
+        _write(tmp_path, "a/b/work/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/Tasks]]")
+        assert _build(tmp_path).out_links["src.md"] == {"a/b/work/Tasks.md"}
+
+    def test_a_whole_path_still_resolves(self, tmp_path):
+        _write(tmp_path, "work/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/Tasks]]")
+        assert _build(tmp_path).out_links["src.md"] == {"work/Tasks.md"}
+
+    def test_a_genuine_collision_is_still_ambiguous(self, tmp_path):
+        _write(tmp_path, "a/work/Tasks.md")
+        _write(tmp_path, "b/work/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/Tasks]]")
+        graph = _build(tmp_path)
+        assert graph.link_counts["ambiguous"] == 1
+        assert candidates_for("work/Tasks", graph.catalog) == [
+            "a/work/Tasks.md",
+            "b/work/Tasks.md",
+        ]
+
+    def test_case_and_unicode_form_still_fold(self, tmp_path):
+        _write(tmp_path, "Work/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/tasks]]")
+        assert _build(tmp_path).unresolved == {}
+
+
+class TestMarkdownModeAgrees:
+    def test_a_markdown_link_to_a_punctuation_variant_resolves(self, tmp_path):
+        # Markdown targets are normalized to full vault-relative paths, so they take the same
+        # component path — the fix must reach them too.
+        _write(tmp_path, "notes/Q1 — Review.md")
+        # Percent-encoded, because a bare space in a destination is not a link per CommonMark —
+        # it needs <> or encoding. That also exercises the decode path.
+        _write(tmp_path, "notes/src.md", "[x](Q1%20-%20Review.md)\n")
+        graph = _build(tmp_path, link_syntax="markdown")
+        assert graph.out_links["notes/src.md"] == {"notes/Q1 — Review.md"}
+
+
+class TestDegenerate:
+    def test_a_trailing_slash_names_nothing(self, tmp_path):
+        _write(tmp_path, "a/b.md")
+        assert candidates_for("a/", _build(tmp_path).catalog) == []
+
+    def test_a_punctuation_only_component_names_nothing(self, tmp_path):
+        _write(tmp_path, "a/b.md")
+        assert candidates_for("a/--", _build(tmp_path).catalog) == []