graphmark 0.7.0__tar.gz → 0.7.1__tar.gz

{graphmark-0.7.0 → graphmark-0.7.1}/CHANGELOG.md

@@ -1,6 +1,66 @@
 # CHANGELOG
 
 
+## v0.7.1 (2026-07-25)
+
+### Bug Fixes
+
+- **graph**: Match path-suffix links on component boundaries (#136)
+  ([#140](https://github.com/cdcoonce/graphmark/pull/140),
+  [`3c23b1a`](https://github.com/cdcoonce/graphmark/commit/3c23b1a04a86cdf1c482075c976ed5db86f4e18e))
+
+`[[work/Tasks]]` resolved to `homework/Tasks.md`. Path-suffix resolution tested a raw string suffix,
+  so nothing required the character before the match to be `/`.
+
+This is the first defect class in this package that fabricates an *edge* rather than moving a link
+  between reported buckets, and it is invisible by construction: the link counts `resolved`, so no
+  bucket looks implausible, while orphans, hubs, clusters, bridges, siloed_notes and PageRank all
+  read a graph that does not describe the vault. The mirror case is equally wrong — when the real
+  folder also exists, the spurious second match makes the resolver decline a correct link and report
+  it ambiguous.
+
+`_matches_path_suffix` requires the match to consume the whole rel_path or be preceded by `/`, and
+  both the resolver and `candidates_for` go through it, so the ambiguity set a consumer is shown can
+  never contain a path the resolver would not have considered.
+
+Measured on the reference vault: 0 occurrences, graph byte-identical. Latent, not absent — it needs
+  one folder whose name ends with another's (`work`/`homework`, `ops`/`devops`,
+  `<x>`/`archive-<x>`), which is ordinary.
+
+- **parse**: Strip a leading UTF-8 BOM before the frontmatter split (#137)
+  ([#141](https://github.com/cdcoonce/graphmark/pull/141),
+  [`e92afd6`](https://github.com/cdcoonce/graphmark/commit/e92afd6484d4d8b966122df1db858cd791b33e0a))
+
+`_FM_RE` is anchored with `.match` and decoding leaves U+FEFF at index 0, so a BOM'd note had no
+  frontmatter at all. One cause, two opposite symptoms: its `aliases:` never registered, so links
+  written against them were phantom breaks (#119's class, reintroduced through the parser); and its
+  frontmatter wikilinks stayed in the body and became phantom edges — the exact failure `_FM_RE`'s
+  own docstring says it exists to prevent. That regex was hardened for CRLF and for a block ending
+  at EOF, but not for the byte that can precede the block.
+
+Stripped on the decoded text, so the frontmatter split, the body and the extractor all see the same
+  string on both decode paths. Leading only: elsewhere U+FEFF is a zero-width no-break space and is
+  legitimate content.
+
+Reference vault: 0 BOM'd notes. Latent, not absent — Windows editors, PowerShell's default Out-File
+  and some git filters emit BOMs.
+
+### Documentation
+
+- **roadmap**: Record Track F's interim finding-method result
+  ([#142](https://github.com/cdcoonce/graphmark/pull/142),
+  [`2e6c368`](https://github.com/cdcoonce/graphmark/commit/2e6c368aa16cd3b0cd5dbf4fe6912dcbe7bb1427))
+
+Four defects (#136 #137 #138 #139) found in one pass after #124-#126 shipped — none by reading link
+  lists, none by the property generator. The method that worked was adversarial reading of the
+  resolver and parser, confirmed by probe. All four measure 0 occurrences on the reference vault.
+
+Names two limits this exposes: the counts cannot surface a wrong answer INSIDE a bucket (#136 files
+  as `resolved`, #138 hides a break in `non-note-file`), and #126's generator draws from an alphabet
+  that never reaches these input classes. Also records the hand audit of both suppressed buckets: 0
+  false suppressions.
+
+
 ## v0.7.0 (2026-07-25)
 
 ### Documentation

{graphmark-0.7.0 → graphmark-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.7.0
+Version: 0.7.1
 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.7.0 → graphmark-0.7.1}/docs/ROADMAP.md

@@ -144,6 +144,29 @@ calibration gate #112 used).
 Track F's own success measure is not slices merged: it is **bugs found by machinery rather than by
 a human reading link lists.** #126's catch rate is the evidence.
 
+_Interim result (2026-07-25, after #124–#126 shipped):_ four more defects — #136, #137, #138, #139 —
+found in one pass, none of them by reading link lists and **none of them by the property generator
+either**. The method that worked was adversarial reading of the resolver and parser against the
+question _"what input could this classify wrongly?"_, then a scripted probe to confirm. All four
+measure **0 occurrences on the reference vault**, which is the point: a single-vault count is not
+evidence of absence, and every one of them is ordinary on some other vault.
+
+Two things this says about the track:
+
+- **The counts alone would not have surfaced these.** #136 fabricates an edge to the wrong note and
+  is filed `resolved`; #138 hides a genuine break inside `non-note-file`. The distribution looks
+  healthy in both cases. Auditable accounting makes _mis-bucketing between reported buckets_
+  visible; it does not make a wrong answer _inside_ a bucket visible. That is a real limit of the
+  Track F thesis, not a gap in its execution.
+- **#126's generator is under-powered where it matters.** It generates vaults from names the
+  resolver already handles. The defect classes live in the input space it does not reach: folder
+  names that are suffixes of other folder names, BOMs, numeric title suffixes, non-ASCII
+  punctuation. Widening the generator's _alphabet_ — not its vault count — is the follow-on.
+
+Audited alongside: the reference vault's two suppressed buckets, by hand — 17 `non-note-file` (all
+genuine `.base`/`.png`) and 40 `intra-note` (all genuine heading refs), 0 false suppressions. A
+suppressed bucket is only trustworthy once someone has read it.
+
 _Deliberately deferred behind this:_ the Track D GitHub Action. It is an adoption play, and adoption
 is not this repo's game; more to the point, shipping a gate that fails other people's builds while
 the tool's own accounting is unauditable is backwards ordering. Generality work (Windows paths,

{graphmark-0.7.0 → graphmark-0.7.1}/pyproject.toml

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

{graphmark-0.7.0 → graphmark-0.7.1}/src/graphmark/graph.py

@@ -54,6 +54,24 @@ 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**.
+
+    ``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.
+
+    The match is legal only when it consumes the whole rel_path or is preceded by ``/``.
+    """
+    lowered = rel_path.lower()
+    if not lowered.endswith(suffix):
+        return False
+    rest = len(lowered) - len(suffix)
+    return rest == 0 or lowered[rest - 1] == "/"
+
+
 def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
     """Every rel_path in ``catalog`` that ``display`` names, sorted; empty if it names none.
 
@@ -71,7 +89,10 @@ def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
     if "/" in target:
         suffix = target.lower() + ".md"
         return sorted(
-            path for paths in catalog.values() for path in paths if path.lower().endswith(suffix)
+            path
+            for paths in catalog.values()
+            for path in paths
+            if _matches_path_suffix(path, suffix)
         )
     return list(catalog.get(_normalize(target), ()))
 
@@ -170,7 +191,7 @@ class NormalizeResolver:
             # Path-suffix resolution: find unique rel_path ending with "display.md"
             suffix = display.lower() + ".md"
             all_paths = self._flatten_paths(catalog)
-            matches = [p for p in all_paths if p.lower().endswith(suffix)]
+            matches = [p for p in all_paths if _matches_path_suffix(p, suffix)]
             return matches[0] if len(matches) == 1 else None
 
         # Bare-link resolution: normalize and look up in catalog

{graphmark-0.7.0 → graphmark-0.7.1}/src/graphmark/parse.py

@@ -119,6 +119,15 @@ def parse_document(path: Path, root: Path) -> Document:
             f"graphmark: warning: {rel_path}: invalid UTF-8, decoded with replacement",
             file=sys.stderr,
         )
+    # A UTF-8 BOM sits ahead of the `---` and defeats _FM_RE's anchored match, so a BOM'd note
+    # would have no frontmatter at all: its aliases would never register (a phantom break) and its
+    # frontmatter wikilinks would stay in the body (a phantom edge — the very failure the regex
+    # above exists to prevent). Stripped here, on the decoded text, so the frontmatter split, the
+    # body and the extractor all see the same string on both decode paths. Leading only: elsewhere
+    # U+FEFF is a zero-width no-break space, which is legitimate content. lstrip rather than a
+    # single removal because double-encoding produces doubled BOMs, and one survivor still breaks
+    # the match.
+    raw = raw.lstrip("")
     m = _FM_RE.match(raw)
     if m:
         frontmatter = _parse_frontmatter(m.group(1))

graphmark-0.7.1/tests/test_bom.py

@@ -0,0 +1,97 @@
+"""A UTF-8 BOM must not defeat frontmatter parsing (#137).
+
+`_FM_RE` is anchored with `.match`, and decoding leaves `U+FEFF` at index 0, so a BOM'd note has no
+frontmatter as far as graphmark is concerned. One cause, two opposite symptoms:
+
+* its `aliases:` never register, so links written against them are phantom breaks — #119's class,
+  reintroduced through the parser;
+* its frontmatter wikilinks stay in the body and become phantom edges — the exact failure `_FM_RE`'s
+  own docstring says it exists to prevent. That regex was hardened for CRLF and for a block ending
+  at EOF, but not for the byte that can precede the block.
+
+The reference vault has no BOM'd notes. A vault synced from a Windows machine ordinarily does.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph
+from graphmark.parse import WikilinkExtractor, parse_document
+
+BOM = ""
+
+
+def _write_bytes(root: Path, rel: str, data: bytes) -> Path:
+    path = root / rel
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    return path
+
+
+def _write(root: Path, rel: str, text: str = "") -> Path:
+    return _write_bytes(root, rel, text.encode("utf-8"))
+
+
+def _build(root: Path, **config_kwargs) -> VaultGraph:
+    return VaultGraph.build(
+        VaultConfig(root=root, **config_kwargs), WikilinkExtractor(), NormalizeResolver()
+    )
+
+
+class TestFrontmatterSplits:
+    def test_a_bom_note_still_parses_its_frontmatter(self, tmp_path):
+        path = _write(tmp_path, "a.md", f"{BOM}---\ntitle: A\n---\nbody\n")
+        doc = parse_document(path, tmp_path)
+        assert doc.frontmatter == {"title": "A"}
+        assert doc.text == "body\n"
+
+    def test_the_bom_never_reaches_the_body(self, tmp_path):
+        # A BOM left in the text would ride along in an extracted display and in every downstream
+        # normalization, so it has to be gone before the frontmatter split, not merely after it.
+        path = _write(tmp_path, "a.md", f"{BOM}body [[Note]]\n")
+        doc = parse_document(path, tmp_path)
+        assert BOM not in doc.text
+        assert WikilinkExtractor().extract(doc.text) == ["Note"]
+
+    def test_an_interior_zero_width_no_break_space_is_content(self, tmp_path):
+        # U+FEFF is only a byte-order mark at position 0; elsewhere it is legitimate text.
+        path = _write(tmp_path, "a.md", f"before{BOM}after\n")
+        assert parse_document(path, tmp_path).text == f"before{BOM}after\n"
+
+    def test_a_bom_survives_the_replacement_decode_path(self, tmp_path):
+        # Invalid UTF-8 falls back to errors="replace"; the BOM must still be stripped there.
+        path = _write_bytes(tmp_path, "a.md", BOM.encode("utf-8") + b"---\ntitle: A\n---\n\xff\n")
+        doc = parse_document(path, tmp_path)
+        assert doc.frontmatter == {"title": "A"}
+        assert not doc.text.startswith(BOM)
+
+
+class TestGraphEffects:
+    def test_a_bom_note_s_aliases_still_resolve(self, tmp_path):
+        _write(tmp_path, "Target.md", f"{BOM}---\naliases: [TGT]\n---\nbody\n")
+        _write(tmp_path, "src.md", "[[TGT]]")
+        graph = _build(tmp_path)
+        assert graph.aliases == {"tgt": "Target.md"}
+        assert graph.unresolved == {}
+        assert graph.out_links["src.md"] == {"Target.md"}
+
+    def test_a_bom_note_s_frontmatter_links_are_not_edges(self, tmp_path):
+        _write(tmp_path, "a.md", f'{BOM}---\nup: "[[Ghost]]"\n---\nbody\n')
+        _write(tmp_path, "Ghost.md", "")
+        graph = _build(tmp_path)
+        assert graph.out_links["a.md"] == set()
+        assert graph.link_counts["resolved"] == 0
+
+
+class TestUnaffected:
+    def test_a_bom_free_note_is_byte_identical(self, tmp_path):
+        path = _write(tmp_path, "a.md", "---\ntitle: A\n---\nbody [[Note]]\n")
+        doc = parse_document(path, tmp_path)
+        assert doc.frontmatter == {"title": "A"}
+        assert doc.text == "body [[Note]]\n"
+
+    def test_a_bom_with_no_frontmatter_leaves_the_body_intact(self, tmp_path):
+        path = _write(tmp_path, "a.md", f"{BOM}# Heading\n")
+        assert parse_document(path, tmp_path).text == "# Heading\n"

graphmark-0.7.1/tests/test_path_suffix.py

@@ -0,0 +1,114 @@
+"""Path-suffix resolution must match on path-component boundaries (#136).
+
+`[[folder/note]]` is resolved by finding the rel_path that *ends with* `folder/note.md`. That test
+was a raw string suffix, so `homework/Tasks.md` satisfied `[[work/Tasks]]` — the character before
+the match was never required to be a separator.
+
+This is the first defect class in this package that fabricates an **edge** rather than moving a
+link between reported buckets. A wrong edge is invisible: the link counts `resolved`, so no bucket
+looks implausible, and every downstream metric (orphans, hubs, clusters, bridges, siloed_notes,
+PageRank) reads a graph that does not describe the vault. The mirror case is just as bad — when
+both `work/Tasks.md` and `homework/Tasks.md` exist the spurious second match makes the resolver
+decline, turning a *correct* link into a reported break.
+
+`candidates_for` mirrors the resolver's matching and is exercised alongside it here: the ambiguity
+set a consumer is shown must never contain a path the resolver would not have considered.
+"""
+
+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, **config_kwargs) -> VaultGraph:
+    return VaultGraph.build(
+        VaultConfig(root=root, **config_kwargs), WikilinkExtractor(), NormalizeResolver()
+    )
+
+
+class TestFolderBoundary:
+    def test_a_longer_folder_name_does_not_satisfy_a_shorter_one(self, tmp_path):
+        # There is no work/ folder in this vault, so the link is broken. Before #136 it silently
+        # produced an edge to homework/Tasks.md.
+        _write(tmp_path, "homework/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/Tasks]]")
+        graph = _build(tmp_path)
+        assert graph.out_links["src.md"] == set()
+        assert graph.unresolved == {"src.md": ["work/Tasks"]}
+
+    def test_the_real_folder_still_wins_when_both_exist(self, tmp_path):
+        # The mirror failure: the spurious homework/ match made the match list length 2, the
+        # resolver declined, and a correct link was reported ambiguous.
+        _write(tmp_path, "work/Tasks.md")
+        _write(tmp_path, "homework/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/Tasks]]")
+        graph = _build(tmp_path)
+        assert graph.out_links["src.md"] == {"work/Tasks.md"}
+        assert graph.unresolved == {}
+
+    def test_a_longer_stem_does_not_satisfy_the_note_part(self, tmp_path):
+        # Same missing boundary one component to the right: "a/b.md" must not be matched by
+        # "dir/xa/b.md" NOR by a file whose stem merely ends in the target's.
+        _write(tmp_path, "notes/my-tasks.md")
+        _write(tmp_path, "src.md", "[[notes/tasks]]")
+        graph = _build(tmp_path)
+        assert graph.unresolved == {"src.md": ["notes/tasks"]}
+
+
+class TestStillResolves:
+    def test_any_depth_of_prefix_above_the_named_folder(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_match_at_the_root(self, tmp_path):
+        # The match is the entire rel_path — there is no preceding "/" to require.
+        _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_fully_qualified_path_from_the_vault_root(self, tmp_path):
+        _write(tmp_path, "a/b/work/Tasks.md")
+        _write(tmp_path, "src.md", "[[a/b/work/Tasks]]")
+        assert _build(tmp_path).out_links["src.md"] == {"a/b/work/Tasks.md"}
+
+    def test_case_insensitivity_survives(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.unresolved == {"src.md": ["work/Tasks"]}
+        assert graph.link_counts["ambiguous"] == 1
+
+
+class TestCandidatesAgree:
+    """candidates_for is the ambiguity set a consumer is shown; it must see exactly what the
+    resolver saw. Two matchers that disagree is the drift this package removed from its consumer."""
+
+    def test_a_non_boundary_path_is_not_offered_as_a_candidate(self, tmp_path):
+        _write(tmp_path, "homework/Tasks.md")
+        _write(tmp_path, "src.md", "[[work/Tasks]]")
+        catalog = _build(tmp_path).catalog
+        assert candidates_for("work/Tasks", catalog) == []
+
+    def test_boundary_matches_are_still_offered(self, tmp_path):
+        _write(tmp_path, "a/work/Tasks.md")
+        _write(tmp_path, "b/work/Tasks.md")
+        _write(tmp_path, "homework/Tasks.md")
+        catalog = _build(tmp_path).catalog
+        assert candidates_for("work/Tasks", catalog) == ["a/work/Tasks.md", "b/work/Tasks.md"]