graphmark 0.5.0__tar.gz → 0.6.0__tar.gz

{graphmark-0.5.0 → graphmark-0.6.0}/CHANGELOG.md

@@ -1,6 +1,90 @@
 # CHANGELOG
 
 
+## v0.6.0 (2026-07-25)
+
+### Bug Fixes
+
+- **parse**: Parse block-style frontmatter lists (#118)
+  ([#120](https://github.com/cdcoonce/graphmark/pull/120),
+  [`723c517`](https://github.com/cdcoonce/graphmark/commit/723c517d30732286fd0e6005996fb36d577042f5))
+
+* chore(release): 0.3.4 [skip ci]
+
+* chore(release): 0.4.0 [skip ci]
+
+* chore(release): 0.5.0 [skip ci]
+
+* fix(parse): parse block-style frontmatter lists (#118)
+
+_parse_frontmatter handled scalars, quoted strings and inline lists, but a block list's item lines
+  contain no colon, so the loop skipped them and the bare `key:` line stored "". Every block-style
+  property in a real vault — aliases:, tags: — silently became an empty string instead of a list.
+
+Block form is what Obsidian's own Properties UI writes, so this is the common case, not the edge
+  case, and Document.frontmatter is public: a consumer reading doc.frontmatter["tags"] got "" rather
+  than a list. Not an error, just quietly wrong data.
+
+Item lines are matched on the leading dash BEFORE the key/value split, so an item containing a colon
+  ("- Note: A Subtitle") stays an item. A block closes at the next key rather than merely pausing —
+  without that, a stray indented line later in a malformed note would silently grow the earlier
+  list, which is misattribution rather than the promised fail-soft drop. That distinction survived
+  the first four mutations and now has its own test.
+
+A `key:` with no items still reads as "" — an empty value, not an empty list — so nothing that
+  parsed before changes shape.
+
+Parity: fixture notes use inline or scalar frontmatter only, so no expected.json can move. A test
+  asserts that property directly rather than leaving it as a claim in the commit message.
+
+Still a targeted scan, not a YAML dependency: this runs over every note in a vault and a note
+  someone is mid-edit must not take the graph down.
+
+---------
+
+Co-authored-by: semantic-release <semantic-release>
+
+### Features
+
+- **graph**: Resolve frontmatter aliases in-package (#119)
+  ([#121](https://github.com/cdcoonce/graphmark/pull/121),
+  [`05bb6ce`](https://github.com/cdcoonce/graphmark/commit/05bb6ced17656a3fb3d1d1798068763b26b68588))
+
+graphmark never read frontmatter during resolution, so every link written against an Obsidian
+  `aliases:` entry was reported broken. Measured on a real 521-note vault: stock graphmark reported
+  23 broken links where the actual count was 0, and dropped 17 edges with them. A 100%
+  false-positive rate in max_unresolved_links — the flagship threshold of graphmark check, the one
+  product this repo offers outward. Larger than the four false-positive classes already fixed
+  (#98/#101/#104/#107) combined.
+
+This reverses a documented decision. the-vault's AliasResolver says "naming policy belongs to the
+  seam, so the fallback lives here rather than in the graph algorithm". That holds for idiosyncratic
+  conventions; aliases: is core Obsidian, and this package claims to work on any Obsidian-family
+  vault. Human-triaged: move it in-package, on by default, since a default that silently produces
+  wrong answers is not fixed by a knob nobody knows to flip. resolve_aliases = false restores the
+  old behavior.
+
+That AliasResolver is the oracle, and the live-vault differential is exact: stock graphmark now
+  reports the same broken-link set as the reference implementation, note for note — 0 and 0, from a
+  51-entry alias map.
+
+Its conservative rules are preserved. An alias colliding with any real note name is dropped at index
+  time, not merely outranked, so a note's own title can never be hijacked and an already-ambiguous
+  basename can't be rescued into resolving. An alias claimed by two notes resolves to nothing. A
+  slash-bearing alias is refused when the map is built, because normalization turns "/" into a space
+  and would otherwise make it reachable from a slash-free display — the lookup-side guard alone does
+  not cover that, which mutation testing caught.
+
+One honest note: rule 1 (resolver before alias) is structurally unreachable given the other two
+  rules — no display can match both a catalog key and an alias key — so mutating the order leaves
+  the suite green. It is kept as insurance against a future relaxation and is documented as untested
+  rather than dressed up as covered.
+
+Parity: this changes what resolves, so it is the most parity-sensitive change since extraction. It
+  is safe only because no frozen fixture declares aliases; a test asserts that property directly so
+  it cannot go stale.
+
+
 ## v0.5.0 (2026-07-25)
 
 ### Features

{graphmark-0.5.0 → graphmark-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.5.0
+Version: 0.6.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
@@ -185,6 +185,7 @@ graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
 graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
 graph.out_of_scope                            # same, for markdown outside the configured scope
+graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
 ```
 
 `catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
@@ -253,10 +254,40 @@ Both constants were calibrated against a human-annotated baseline of a real vaul
 rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
 for the method and the measured result.
 
+## Frontmatter aliases
+
+Obsidian's `aliases:` property declares additional real names for a note, so links written against
+one resolve like any other link. Block, inline and scalar forms all work:
+
+```yaml
+---
+aliases:
+  - Mood Tracker
+  - mood-tracker
+---
+```
+
+`[[Mood Tracker]]` now resolves to `2026-04-11-mood-tracker.md` and produces a real edge. On a
+521-note vault this was the difference between **23 reported broken links and 0** — every one of the
+23 a false positive, plus 17 edges that were silently missing.
+
+Three rules keep it conservative:
+
+- **A real note name always wins.** An alias can never hijack a link to a note that actually bears
+  that name.
+- **An alias that collides with any real note name is dropped entirely** — not merely outranked, so
+  an already-ambiguous basename can't be rescued into resolving by someone's alias.
+- **An alias claimed by two notes resolves to nothing**, the same refusal applied to colliding
+  basenames.
+
+Set `resolve_aliases = false` for strict basename-only resolution. `graph.aliases` exposes the
+resolved map.
+
 ## Configuration
 
 ```toml
 root = "."                                    # required unless --root is passed
+resolve_aliases = true                        # resolve frontmatter aliases: (default true)
 scoped_folders = ["brain", "work"]            # limit the vault to these top-level folders
 excluded_dirs = [".git", "templates"]         # skip notes under these directories
 rules_files = ["CLAUDE.md", "CLAUDE.local.md"]  # agent-rules files, not vault content

{graphmark-0.5.0 → graphmark-0.6.0}/README.md

@@ -158,6 +158,7 @@ graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
 graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
 graph.out_of_scope                            # same, for markdown outside the configured scope
+graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
 ```
 
 `catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
@@ -226,10 +227,40 @@ Both constants were calibrated against a human-annotated baseline of a real vaul
 rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
 for the method and the measured result.
 
+## Frontmatter aliases
+
+Obsidian's `aliases:` property declares additional real names for a note, so links written against
+one resolve like any other link. Block, inline and scalar forms all work:
+
+```yaml
+---
+aliases:
+  - Mood Tracker
+  - mood-tracker
+---
+```
+
+`[[Mood Tracker]]` now resolves to `2026-04-11-mood-tracker.md` and produces a real edge. On a
+521-note vault this was the difference between **23 reported broken links and 0** — every one of the
+23 a false positive, plus 17 edges that were silently missing.
+
+Three rules keep it conservative:
+
+- **A real note name always wins.** An alias can never hijack a link to a note that actually bears
+  that name.
+- **An alias that collides with any real note name is dropped entirely** — not merely outranked, so
+  an already-ambiguous basename can't be rescued into resolving by someone's alias.
+- **An alias claimed by two notes resolves to nothing**, the same refusal applied to colliding
+  basenames.
+
+Set `resolve_aliases = false` for strict basename-only resolution. `graph.aliases` exposes the
+resolved map.
+
 ## Configuration
 
 ```toml
 root = "."                                    # required unless --root is passed
+resolve_aliases = true                        # resolve frontmatter aliases: (default true)
 scoped_folders = ["brain", "work"]            # limit the vault to these top-level folders
 excluded_dirs = [".git", "templates"]         # skip notes under these directories
 rules_files = ["CLAUDE.md", "CLAUDE.local.md"]  # agent-rules files, not vault content

{graphmark-0.5.0 → graphmark-0.6.0}/pyproject.toml

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

{graphmark-0.5.0 → graphmark-0.6.0}/src/graphmark/__init__.py

@@ -33,6 +33,7 @@ from graphmark.graph import (
     LinkDiagnosis,
     NormalizeResolver,
     VaultGraph,
+    build_aliases,
     build_catalog,
     candidates_for,
     diagnose,
@@ -112,6 +113,7 @@ __all__ = [
     "active_dismissed_sigs",
     "bridges",
     "build",
+    "build_aliases",
     "build_catalog",
     "candidates_for",
     "diagnose",

{graphmark-0.5.0 → graphmark-0.6.0}/src/graphmark/config.py

@@ -44,6 +44,9 @@ class VaultConfig:
     excluded_dirs: list[str] = field(default_factory=list)
     rules_files: list[str] = field(default_factory=lambda: ["CLAUDE.md", "CLAUDE.local.md"])
     transient_prefixes: tuple[str, ...] = ()
+    # Obsidian's `aliases:` property names a note, so links written against one resolve by
+    # default. Set False for strict basename-only resolution.
+    resolve_aliases: bool = True
     check: CheckPolicy = field(default_factory=CheckPolicy)
 
     def __post_init__(self) -> None:
@@ -118,5 +121,6 @@ def load_config(path: str | Path, *, root_override: str | Path | None = None) ->
         excluded_dirs=data.get("excluded_dirs", []),
         rules_files=data.get("rules_files", ["CLAUDE.md", "CLAUDE.local.md"]),
         transient_prefixes=tuple(data.get("transient_prefixes", [])),
+        resolve_aliases=bool(data.get("resolve_aliases", True)),
         check=_parse_check(data, path),
     )

{graphmark-0.5.0 → graphmark-0.6.0}/src/graphmark/graph.py

@@ -76,6 +76,43 @@ def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
     return list(catalog.get(_normalize(target), ()))
 
 
+def build_aliases(docs: list[Document], catalog: dict[str, list[str]]) -> dict[str, str]:
+    """Map normalized alias → rel_path, for aliases that unambiguously name one note.
+
+    Obsidian's ``aliases:`` property declares additional real names for a note, so a link written
+    against one is not a broken link. Two rules keep this conservative, and both matter:
+
+    * **An alias that collides with any real note name is dropped entirely** — not merely
+      outranked. A note's own title must never be hijackable by someone else's alias, and an
+      already-ambiguous basename must not be rescued into resolving by a third note's alias.
+    * **An alias claimed by two or more notes resolves to nothing** — the same refusal graphmark
+      already applies to colliding basenames. Ambiguity stays ambiguous.
+
+    Alias keys go through ``_normalize``, the function that builds catalog keys, so an alias and a
+    note name can never drift apart on case or punctuation.
+    """
+    claims: dict[str, set[str]] = {}
+    for doc in docs:
+        raw = doc.frontmatter.get("aliases")
+        # A scalar is one alias; a list is many; anything else (a number, a mapping, a missing
+        # key) yields none rather than raising — a note someone is mid-edit must not break a build.
+        if isinstance(raw, str):
+            values = [raw]
+        elif isinstance(raw, list):
+            values = [v for v in raw if isinstance(v, str)]
+        else:
+            continue
+        for alias in values:
+            # A path is not a name: "[[folder/note]]" is resolved by path suffix, never by alias.
+            if "/" in alias:
+                continue
+            key = _normalize(alias)
+            if not key or key in catalog:
+                continue
+            claims.setdefault(key, set()).add(doc.rel_path)
+    return {key: paths.pop() for key, paths in claims.items() if len(paths) == 1}
+
+
 def _is_intra_note_reference(display: str) -> bool:
     """True for a link that targets no note, e.g. ``[[#Heading]]`` or ``[[#^block]]``.
 
@@ -269,6 +306,7 @@ def _diagnose(
     catalog: dict[str, list[str]],
     out_of_scope: dict[str, list[str]],
     resolver: Resolver,
+    aliases: dict[str, str] | None = None,
 ) -> LinkDiagnosis:
     """Classify one display against already-built resolution state.
 
@@ -284,6 +322,22 @@ def _diagnose(
     if target is not None:
         return LinkDiagnosis(display=display, target=target, reason="resolved")
 
+    # The resolver runs first, so a real note named X always beats an alias X — otherwise renaming
+    # a note could silently hijack live links. An alias hit is a genuine resolution, not a
+    # consolation: it names the note as surely as the filename does.
+    #
+    # Given the rules build_aliases already enforces, this ordering is defense in depth rather
+    # than load-bearing: an alias key can never collide with a catalog key (dropped at index
+    # time), and a path-qualified display is excluded from alias lookup below, so no display can
+    # match both paths. Mutating the order leaves the suite green, which is expected — the
+    # ordering is insurance against a future relaxation of those rules, not the mechanism.
+    if aliases:
+        stripped = _strip_display(display)
+        if stripped and "/" not in stripped:
+            aliased = aliases.get(_normalize(stripped))
+            if aliased is not None:
+                return LinkDiagnosis(display=display, target=aliased, reason="resolved")
+
     # The resolver declined. Whether it declined because nothing matched or because too much did
     # is the distinction consumers need, and only the catalog can answer it.
     collisions = candidates_for(display, catalog)
@@ -318,7 +372,7 @@ def diagnose(graph: VaultGraph, display: str, *, suggest: int = 0) -> LinkDiagno
     """
     if suggest < 0:
         raise ValueError(f"suggest must be >= 0, got {suggest}")
-    diagnosis = _diagnose(display, graph.catalog, graph.out_of_scope, graph.resolver)
+    diagnosis = _diagnose(display, graph.catalog, graph.out_of_scope, graph.resolver, graph.aliases)
     if suggest and diagnosis.reason == "missing":
         return replace(diagnosis, candidates=suggest_notes(display, graph.catalog, suggest))
     return diagnosis
@@ -348,6 +402,7 @@ class VaultGraph:
         catalog: dict[str, list[str]] | None = None,
         out_of_scope: dict[str, list[str]] | None = None,
         resolver: Resolver | None = None,
+        aliases: dict[str, str] | None = None,
     ) -> None:
         self.nodes = nodes
         self.out_links = out_links
@@ -355,6 +410,7 @@ class VaultGraph:
         self.unresolved = unresolved if unresolved is not None else {}
         self.catalog = catalog if catalog is not None else {}
         self.out_of_scope = out_of_scope if out_of_scope is not None else {}
+        self.aliases = aliases if aliases is not None else {}
         # Retained so diagnose() answers with the same resolver that built the graph; a
         # pluggable Resolver that disagreed with the graph it describes would be worse than none.
         self.resolver: Resolver = resolver if resolver is not None else NormalizeResolver()
@@ -398,6 +454,7 @@ class VaultGraph:
         docs = [parse_document(p, root) for p in md_files]
         nodes = {doc.rel_path: doc for doc in docs}
         catalog = build_catalog(docs)
+        aliases = build_aliases(docs, catalog) if config.resolve_aliases else {}
 
         out_links: dict[str, set[str]] = {rel: set() for rel in nodes}
         back_links: dict[str, set[str]] = {rel: set() for rel in nodes}
@@ -411,7 +468,7 @@ class VaultGraph:
         broken = {"ambiguous", "missing"}
         for doc in docs:
             for display in extractor.extract(doc.text):
-                d = _diagnose(display, catalog, out_of_scope, resolver)
+                d = _diagnose(display, catalog, out_of_scope, resolver, aliases)
                 if d.reason in broken:
                     unresolved.setdefault(doc.rel_path, []).append(display)
                 elif d.target is not None and d.target != doc.rel_path:
@@ -421,4 +478,6 @@ class VaultGraph:
             for dst in targets:
                 back_links[dst].add(src)
 
-        return cls(nodes, out_links, back_links, unresolved, catalog, out_of_scope, resolver)
+        return cls(
+            nodes, out_links, back_links, unresolved, catalog, out_of_scope, resolver, aliases
+        )

{graphmark-0.5.0 → graphmark-0.6.0}/src/graphmark/parse.py

@@ -45,10 +45,38 @@ def _strip_fenced_blocks(text: str) -> str:
     return "".join(out)
 
 
+#: A block-list item line: leading whitespace, a dash, then the value. Checked before the
+#: key/value split because an item may itself contain a colon ("- Note: A Subtitle") — the dash
+#: decides, not the colon.
+_BLOCK_ITEM_RE = re.compile(r"^\s+-\s*(.*)$")
+
+
 def _parse_frontmatter(raw: str) -> dict:
-    """Minimal YAML-like frontmatter parser covering scalar, quoted-string, inline-list."""
+    """Minimal YAML-like frontmatter parser: scalar, quoted-string, inline-list, block-list.
+
+    Deliberately a targeted scan rather than a YAML dependency — this runs over every note in a
+    vault, and a note someone is mid-edit must not take the graph down. Anything unparseable
+    yields nothing rather than raising.
+
+    Block lists (``key:`` followed by indented ``- item`` lines) are what Obsidian's own
+    Properties UI writes, so they are the common form in real vaults, not an edge case. They
+    produce the same ``list[str]`` an inline list does. A ``key:`` with no items that follow stays
+    ``""`` — an empty value, not an empty list.
+    """
     result: dict = {}
+    current_list_key: str | None = None
     for line in raw.splitlines():
+        item = _BLOCK_ITEM_RE.match(line)
+        if item is not None and current_list_key is not None:
+            value = item.group(1).strip().strip("\"'")
+            if value:
+                # The key held "" until its first item arrived; replace it with the list.
+                if not isinstance(result.get(current_list_key), list):
+                    result[current_list_key] = []
+                result[current_list_key].append(value)
+            continue
+
+        current_list_key = None
         if ":" not in line:
             continue
         key, _, value = line.partition(":")
@@ -59,6 +87,9 @@ def _parse_frontmatter(raw: str) -> dict:
             result[key] = [i for i in items if i]
         else:
             result[key] = value.strip("\"'")
+            # A bare "key:" may open a block list; the next line decides.
+            if not value:
+                current_list_key = key
     return result
 
 

graphmark-0.6.0/tests/test_aliases.py

@@ -0,0 +1,256 @@
+"""Frontmatter `aliases:` resolution — a declared alias is a real name for a note.
+
+Obsidian's `aliases:` property is a core feature, not a vault convention, and graphmark claims to
+work on any Obsidian-family vault. Until now it never read frontmatter during resolution, so every
+link written against an alias was reported broken. Measured on a real 521-note vault: stock
+graphmark reported **23 broken links against an actual 0**, and dropped the corresponding edges —
+a 100% false-positive rate in `max_unresolved_links`, the flagship `graphmark check` threshold.
+
+The behavioral spec is the reference implementation this replaces (the consumer's `AliasResolver`).
+Its six rules, each of which has a test below:
+
+  1. the base resolver runs FIRST — a real note named X always beats an alias X, or renaming a note
+     could silently hijack live links. NOTE: rules 3 and 4 make this ordering structurally
+     unreachable (no display can match both a catalog key and an alias key), so mutating the order
+     leaves this suite green. It is kept as insurance against a future relaxation of those rules,
+     and is deliberately not claimed as test-covered;
+  2. an alias claimed by two or more notes resolves to nothing — the same refusal graphmark already
+     applies to colliding basenames;
+  3. an alias colliding with any real note name is dropped ENTIRELY, not merely deprioritized;
+  4. a path-qualified display never matches an alias — `[[folder/note]]` is a path, not a name;
+  5. alias keys normalize through the same function as note names, so the two cannot drift;
+  6. fail-soft — an unreadable or unparseable note yields no aliases, never an exception.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph, diagnose
+from graphmark.parse import WikilinkExtractor
+
+
+def _write(root: Path, rel: str, aliases: list[str] | None = None, body: str = "") -> None:
+    path = root / rel
+    path.parent.mkdir(parents=True, exist_ok=True)
+    front = ""
+    if aliases is not None:
+        items = "".join(f"  - {a}\n" for a in aliases)
+        front = f"---\naliases:\n{items}---\n\n"
+    path.write_text(front + body, encoding="utf-8")
+
+
+def _build(root: Path, **config_kwargs) -> VaultGraph:
+    return VaultGraph.build(
+        VaultConfig(root=root, **config_kwargs), WikilinkExtractor(), NormalizeResolver()
+    )
+
+
+class TestAliasResolution:
+    def test_a_link_to_an_alias_resolves_to_the_note(self, tmp_path):
+        _write(tmp_path, "notes/2026-04-11-mood-tracker.md", aliases=["Mood Tracker"])
+        _write(tmp_path, "src.md", body="See [[Mood Tracker]].\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["src.md"] == {"notes/2026-04-11-mood-tracker.md"}
+
+    def test_an_alias_link_diagnoses_as_resolved(self, tmp_path):
+        _write(tmp_path, "notes/target.md", aliases=["Other Name"])
+        _write(tmp_path, "src.md", body="See [[Other Name]].\n")
+        d = diagnose(_build(tmp_path), "Other Name")
+        assert (d.reason, d.target) == ("resolved", "notes/target.md")
+
+    def test_several_aliases_on_one_note_all_resolve(self, tmp_path):
+        _write(tmp_path, "n.md", aliases=["First", "Second", "Third"])
+        _write(tmp_path, "src.md", body="[[First]] [[Second]] [[Third]]\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["src.md"] == {"n.md"}
+
+    @pytest.mark.parametrize(
+        "display", ["Mood Tracker", "mood tracker", "MOOD TRACKER", "Mood-Tracker"]
+    )
+    def test_alias_keys_normalize_like_note_names(self, tmp_path, display):
+        # Rule 5: same normalization as note names — case, punctuation and whitespace all fold.
+        _write(tmp_path, "n.md", aliases=["Mood Tracker"])
+        _write(tmp_path, "src.md", body=f"See [[{display}]].\n")
+        assert _build(tmp_path).unresolved == {}
+
+    @pytest.mark.parametrize("form", ["Alias Name|shown", "Alias Name#Section", "Alias Name.md"])
+    def test_alias_display_forms_resolve(self, tmp_path, form):
+        _write(tmp_path, "n.md", aliases=["Alias Name"])
+        _write(tmp_path, "src.md", body=f"See [[{form}]].\n")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_inline_alias_lists_work_too(self, tmp_path):
+        (tmp_path / "n.md").write_text("---\naliases: [One, Two]\n---\n", encoding="utf-8")
+        (tmp_path / "src.md").write_text("See [[Two]].\n", encoding="utf-8")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_a_scalar_alias_works(self, tmp_path):
+        (tmp_path / "n.md").write_text("---\naliases: Solo Name\n---\n", encoding="utf-8")
+        (tmp_path / "src.md").write_text("See [[Solo Name]].\n", encoding="utf-8")
+        assert _build(tmp_path).unresolved == {}
+
+
+class TestRealNamesWin:
+    """Rule 1 + rule 3 — the anti-hijacking guarantees."""
+
+    def test_a_real_note_beats_an_alias_of_the_same_name(self, tmp_path):
+        _write(tmp_path, "real/Target.md")
+        _write(tmp_path, "other/impostor.md", aliases=["Target"])
+        _write(tmp_path, "src.md", body="See [[Target]].\n")
+        graph = _build(tmp_path)
+        assert graph.out_links["src.md"] == {"real/Target.md"}
+
+    def test_an_alias_colliding_with_a_real_name_is_dropped_entirely(self, tmp_path):
+        # Rule 3: not merely deprioritized. Two notes named "note" make the bare link ambiguous;
+        # a third note claiming "note" as an alias must not rescue it into resolving.
+        _write(tmp_path, "one/note.md")
+        _write(tmp_path, "two/note.md")
+        _write(tmp_path, "three/other.md", aliases=["note"])
+        _write(tmp_path, "src.md", body="See [[note]].\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {"src.md": ["note"]}
+        assert graph.out_links["src.md"] == set()
+
+    def test_a_notes_own_alias_does_not_shadow_another_notes_title(self, tmp_path):
+        _write(tmp_path, "a/Real Title.md")
+        _write(tmp_path, "b/other.md", aliases=["Real Title"])
+        _write(tmp_path, "src.md", body="See [[Real Title]].\n")
+        assert _build(tmp_path).out_links["src.md"] == {"a/Real Title.md"}
+
+
+class TestAmbiguousAliases:
+    """Rule 2 — ambiguity stays ambiguous."""
+
+    def test_an_alias_claimed_by_two_notes_resolves_to_nothing(self, tmp_path):
+        _write(tmp_path, "a.md", aliases=["Shared"])
+        _write(tmp_path, "b.md", aliases=["Shared"])
+        _write(tmp_path, "src.md", body="See [[Shared]].\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {"src.md": ["Shared"]}
+        assert graph.out_links["src.md"] == set()
+
+    def test_an_alias_claimed_twice_by_the_same_note_still_resolves(self, tmp_path):
+        # Duplicate within one note is not a conflict — one claimant, one target.
+        _write(tmp_path, "a.md", aliases=["Shared", "Shared"])
+        _write(tmp_path, "src.md", body="See [[Shared]].\n")
+        assert _build(tmp_path).out_links["src.md"] == {"a.md"}
+
+    def test_a_contested_alias_does_not_poison_an_uncontested_one(self, tmp_path):
+        _write(tmp_path, "a.md", aliases=["Shared", "Unique A"])
+        _write(tmp_path, "b.md", aliases=["Shared"])
+        _write(tmp_path, "src.md", body="[[Shared]] and [[Unique A]]\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {"src.md": ["Shared"]}
+        assert graph.out_links["src.md"] == {"a.md"}
+
+
+class TestPathQualifiedLinks:
+    """Rule 4 — a path is not a name."""
+
+    def test_a_path_qualified_display_never_matches_an_alias(self, tmp_path):
+        _write(tmp_path, "n.md", aliases=["folder/thing"])
+        _write(tmp_path, "src.md", body="See [[folder/thing]].\n")
+        assert _build(tmp_path).unresolved == {"src.md": ["folder/thing"]}
+
+    def test_a_slash_bearing_alias_is_rejected_at_index_time(self, tmp_path):
+        # The lookup-side guard (skip alias lookup for path-qualified displays) is not enough on
+        # its own: normalization turns "/" into a space, so an alias "folder/thing" would key as
+        # "folder thing" and be reachable from a slash-free display. The reference implementation
+        # refuses such an alias when building the map, and so must this.
+        _write(tmp_path, "n.md", aliases=["folder/thing"])
+        _write(tmp_path, "src.md", body="See [[folder thing]].\n")
+        graph = _build(tmp_path)
+        assert graph.aliases == {}
+        assert graph.unresolved == {"src.md": ["folder thing"]}
+
+    def test_path_resolution_still_works_alongside_aliases(self, tmp_path):
+        _write(tmp_path, "docs/deep/note.md", aliases=["Nickname"])
+        _write(tmp_path, "src.md", body="[[deep/note]] and [[Nickname]]\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["src.md"] == {"docs/deep/note.md"}
+
+
+class TestScopeAndFailSoft:
+    def test_an_out_of_scope_note_contributes_no_aliases(self, tmp_path):
+        # Out-of-scope notes are not part of the graph, so their names — including alias names —
+        # cannot become link targets.
+        _write(tmp_path, "docs/a.md")
+        _write(tmp_path, "templates/t.md", aliases=["Template Nickname"])
+        _write(tmp_path, "docs/src.md", body="See [[Template Nickname]].\n")
+        graph = _build(tmp_path, scoped_folders=["docs"])
+        assert graph.unresolved == {"docs/src.md": ["Template Nickname"]}
+
+    def test_a_note_without_frontmatter_is_fine(self, tmp_path):
+        _write(tmp_path, "n.md")
+        _write(tmp_path, "src.md", body="See [[Nowhere]].\n")
+        assert _build(tmp_path).unresolved == {"src.md": ["Nowhere"]}
+
+    def test_an_empty_alias_list_is_fine(self, tmp_path):
+        (tmp_path / "n.md").write_text("---\naliases:\n---\n", encoding="utf-8")
+        (tmp_path / "src.md").write_text("See [[Nowhere]].\n", encoding="utf-8")
+        assert _build(tmp_path).unresolved == {"src.md": ["Nowhere"]}
+
+    def test_an_empty_alias_entry_is_ignored(self, tmp_path):
+        (tmp_path / "n.md").write_text('---\naliases:\n  - ""\n  - Real\n---\n', encoding="utf-8")
+        (tmp_path / "src.md").write_text("See [[Real]].\n", encoding="utf-8")
+        assert _build(tmp_path).unresolved == {}
+
+    def test_a_non_list_aliases_value_does_not_raise(self, tmp_path):
+        # Rule 6: anything unparseable yields no aliases rather than taking the graph down.
+        (tmp_path / "n.md").write_text("---\naliases: 42\n---\n", encoding="utf-8")
+        (tmp_path / "src.md").write_text("See [[Nowhere]].\n", encoding="utf-8")
+        assert _build(tmp_path).unresolved == {"src.md": ["Nowhere"]}
+
+    def test_a_self_alias_link_is_not_an_edge(self, tmp_path):
+        _write(tmp_path, "solo.md", aliases=["Me"], body="I link to [[Me]].\n")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {}
+        assert graph.out_links["solo.md"] == set()
+
+
+class TestAliasesAreInspectable:
+    def test_the_graph_exposes_the_resolved_alias_map(self, tmp_path):
+        _write(tmp_path, "n.md", aliases=["Nickname"])
+        graph = _build(tmp_path)
+        assert graph.aliases == {"nickname": "n.md"}
+
+    def test_contested_and_colliding_aliases_are_absent_from_the_map(self, tmp_path):
+        _write(tmp_path, "real.md")
+        _write(tmp_path, "a.md", aliases=["Shared", "real"])
+        _write(tmp_path, "b.md", aliases=["Shared"])
+        assert _build(tmp_path).aliases == {}
+
+    def test_directly_constructed_graph_defaults_to_no_aliases(self):
+        assert VaultGraph(nodes={}, out_links={}, back_links={}).aliases == {}
+
+
+class TestConfigKnob:
+    def test_aliases_can_be_disabled(self, tmp_path):
+        _write(tmp_path, "n.md", aliases=["Nickname"])
+        _write(tmp_path, "src.md", body="See [[Nickname]].\n")
+        graph = _build(tmp_path, resolve_aliases=False)
+        assert graph.unresolved == {"src.md": ["Nickname"]}
+        assert graph.aliases == {}
+
+    def test_the_default_is_on(self, tmp_path):
+        cfg = VaultConfig(root=tmp_path)
+        assert cfg.resolve_aliases is True
+
+
+class TestFixtureParity:
+    def test_no_fixture_note_declares_aliases(self):
+        # The parity argument: this change alters what resolves, so it is the most parity-sensitive
+        # change since extraction. It is safe only because no frozen fixture uses aliases. Asserted
+        # rather than claimed, so it cannot go stale.
+        fixtures = Path(__file__).parent / "fixtures"
+        offenders = [
+            str(n) for n in fixtures.rglob("*.md") if "aliases:" in n.read_text(encoding="utf-8")
+        ]
+        assert offenders == []

{graphmark-0.5.0 → graphmark-0.6.0}/tests/test_parse.py

@@ -164,3 +164,94 @@ class TestFrontmatterLineEndings:
         doc = self._parse(tmp_path, "fm_only_crlf.md", b"---\r\ntitle: Note\r\n---")
         assert doc.frontmatter == {"title": "Note"}
         assert doc.text == ""
+
+
+class TestBlockStyleLists:
+    """`key:` followed by `  - item` lines — what Obsidian's Properties UI actually writes.
+
+    The parser handled scalars, quoted strings and inline lists, but a block list's item lines
+    contain no `:` so the loop skipped them, and the bare `key:` line stored `''`. Every
+    block-style property in a real vault — `aliases:`, `tags:` — silently became an empty string
+    rather than a list. Not an error, just quietly wrong data behind a public attribute.
+    """
+
+    def _fm(self, raw: str) -> dict:
+        from graphmark.parse import _parse_frontmatter
+
+        return _parse_frontmatter(raw)
+
+    def test_block_list_parses_to_a_list(self):
+        assert self._fm("aliases:\n  - One\n  - Two") == {"aliases": ["One", "Two"]}
+
+    def test_a_single_item_block_is_still_a_list(self):
+        assert self._fm("tags:\n  - project") == {"tags": ["project"]}
+
+    def test_inline_lists_are_unchanged(self):
+        assert self._fm("aliases: [One, Two]") == {"aliases": ["One", "Two"]}
+
+    def test_scalars_are_unchanged(self):
+        assert self._fm("title: Solo") == {"title": "Solo"}
+
+    def test_quoted_scalars_are_unchanged(self):
+        assert self._fm('description: "a thing"') == {"description": "a thing"}
+
+    def test_an_empty_key_stays_an_empty_string(self):
+        # A key with no items is an empty VALUE, not an empty list — unchanged behavior.
+        assert self._fm("aliases:\ndate: 2026-07-25") == {"aliases": "", "date": "2026-07-25"}
+
+    def test_the_block_ends_at_the_next_key(self):
+        parsed = self._fm("aliases:\n  - One\n  - Two\ndate: 2026-07-25\ntitle: T")
+        assert parsed == {"aliases": ["One", "Two"], "date": "2026-07-25", "title": "T"}
+
+    def test_a_stray_item_after_another_key_is_not_absorbed(self):
+        # The block must CLOSE at the next key, not merely pause. Without that, a malformed or
+        # mid-edit note silently grows the earlier list — the fail-soft promise says drop the
+        # junk, not misattribute it.
+        parsed = self._fm("aliases:\n  - One\ndate: 2026-07-25\n  - Stray")
+        assert parsed == {"aliases": ["One"], "date": "2026-07-25"}
+
+    def test_two_block_lists_in_one_document(self):
+        parsed = self._fm("aliases:\n  - A\ntags:\n  - x\n  - y")
+        assert parsed == {"aliases": ["A"], "tags": ["x", "y"]}
+
+    def test_quoted_block_items_are_unquoted(self):
+        assert self._fm("aliases:\n  - \"Mood Tracker\"\n  - 'mood-tracker'") == {
+            "aliases": ["Mood Tracker", "mood-tracker"]
+        }
+
+    def test_empty_items_are_dropped(self):
+        assert self._fm("aliases:\n  - One\n  -\n  - Two") == {"aliases": ["One", "Two"]}
+
+    def test_items_containing_a_colon_are_not_read_as_keys(self):
+        # "- Note: A Subtitle" is an item, not a nested key — the dash decides.
+        assert self._fm("aliases:\n  - Note: A Subtitle") == {"aliases": ["Note: A Subtitle"]}
+
+    def test_a_block_list_survives_a_real_note(self, tmp_path):
+        note = tmp_path / "n.md"
+        note.write_text(
+            "---\naliases:\n  - Mood Tracker\ntags:\n  - health\n---\n\nBody [[x]].\n",
+            encoding="utf-8",
+        )
+        doc = parse_document(note, tmp_path)
+        assert doc.frontmatter["aliases"] == ["Mood Tracker"]
+        assert doc.frontmatter["tags"] == ["health"]
+        assert "Body" in doc.text
+
+
+class TestFixtureFrontmatterUnchanged:
+    def test_no_fixture_note_uses_a_block_list(self):
+        # The parity argument for this change: fixture notes use inline/scalar frontmatter only,
+        # so no expected.json can move. If this ever fails, re-check the oracles before shipping.
+        import re
+
+        block_key = re.compile(r"^[A-Za-z_][\w-]*:\s*$", re.MULTILINE)
+        fixtures = Path(__file__).parent / "fixtures"
+        offenders = []
+        for note in fixtures.rglob("*.md"):
+            raw = note.read_text(encoding="utf-8")
+            if not raw.startswith("---"):
+                continue
+            end = raw.find("\n---", 3)
+            if block_key.search(raw[3:end] if end != -1 else raw[3:]):
+                offenders.append(str(note))
+        assert offenders == []

{graphmark-0.5.0 → graphmark-0.6.0}/tests/test_public_api.py

@@ -117,6 +117,7 @@ class TestPublicSurface:
         "diagnose",
         "LinkDiagnosis",
         "DIAGNOSIS_REASONS",
+        "build_aliases",
         "candidates_for",
         "suggest_notes",
         "SUGGEST_MAX_MATCHES",