graphmark 0.7.0__tar.gz → 0.7.2__tar.gz

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

@@ -1,6 +1,175 @@
 # CHANGELOG
 
 
+## v0.7.2 (2026-07-25)
+
+### Bug Fixes
+
+- **cli**: Accept --config/--root after the subcommand (#130)
+  ([#148](https://github.com/cdcoonce/graphmark/pull/148),
+  [`1a89e2e`](https://github.com/cdcoonce/graphmark/commit/1a89e2ef542581f076200a29ddd04e0773cbc2dd))
+
+Every CLI example in the README failed. `--config` and `--root` were defined on the parent parser
+  before `add_subparsers`, so argparse accepted them only BEFORE the subcommand, while all ten
+  examples in the CLI block — plus the `check` ones — are written the other way. The README is the
+  PyPI landing page, so the first thing a new user copies errored.
+
+Both options are now attached to every subparser too, under a separate dest, and reconciled after
+  parsing (argparse would otherwise let the subparser's default overwrite a value the top-level
+  parser had already read). Both collect with action="append", so a repeat within one position is
+  caught as well as one across the two: conflicting values are a usage error, not a silent
+  last-wins.
+
+The actual defect was that the docs and the parser had no shared test — the suite used the working
+  form exclusively. `tests/test_readme_examples.py` now extracts every `graphmark ...` invocation
+  from README.md and runs it, so an example that stops working fails the gate instead of shipping.
+
+- **graph**: Fold non-ASCII punctuation in _normalize (#139)
+  ([#145](https://github.com/cdcoonce/graphmark/pull/145),
+  [`cef4484`](https://github.com/cdcoonce/graphmark/commit/cef448405c1d59577c85ff4f8723299f3ee74dbc))
+
+`string.punctuation` is ASCII-only, so every non-ASCII mark survived normalization and then had to
+  be typed byte-for-byte: an em-dash title was unreachable from a typed hyphen, a curly apostrophe
+  from a straight one, `…` from `...`. The catalog key literally retained the mark while an
+  ASCII-typed display normalized it away, so the two could never meet — while Obsidian's own
+  switcher resolves it.
+
+`_fold_punctuation` folds by Unicode category (P* and S*) instead, a superset of the old ASCII
+  table, so pure-ASCII results are unchanged. The ASCII translate table stays the fast path; the
+  cached per-character category lookup runs only on strings that still hold non-ASCII after it.
+
+Builds on #123: NFC composition runs first, so a decomposed accent is a single letter rather than a
+  letter plus a combining mark this fold must not touch.
+
+Path-suffix matching deliberately still folds only case and form — a "/" is structural there and
+  punctuation folding needs the extension handled first. Follow-up filed.
+
+Reference vault: 531 notes, link counts identical, build 207 ms.
+
+- **graph**: Normalize Unicode form before comparing names (#123)
+  ([#144](https://github.com/cdcoonce/graphmark/pull/144),
+  [`9251554`](https://github.com/cdcoonce/graphmark/commit/9251554691723e7b6ca1d11bf0b7ddb1dffed002))
+
+macOS's HFS+/APFS store filenames decomposed (NFD: `é` is `e` + U+0301) while text typed in an
+  editor is composed (NFC: a single U+00E9). `_normalize` lowercased, folded punctuation and
+  collapsed whitespace but never normalized Unicode form, so the two strings never compared equal
+  and an accented note title was a phantom broken link. Obsidian resolves it fine.
+
+`_fold_case` does NFC-then-lowercase and is shared by `_normalize` and by path-suffix matching — the
+  one comparison that does not go through `_normalize` — so no comparison in the module can be left
+  in the wrong form. Note names, aliases and path-qualified links all fold identically as a result.
+
+Eighth false-positive class in `unresolved`. The reference vault is unaffected (its only non-ASCII
+  filenames are em-dashes, which have no decomposition — which is exactly why this stayed invisible
+  there); link counts byte-identical.
+
+- **graph**: Require a letter in a file extension (#138)
+  ([#147](https://github.com/cdcoonce/graphmark/pull/147),
+  [`4206cc5`](https://github.com/cdcoonce/graphmark/commit/4206cc5f941e5f0967202ac0b99390a55ab0393e))
+
+`_targets_non_note_file` treated any trailing `.` + 1-10 alphanumerics as an extension, so
+  `[[Meeting 3.5]]` with no such note was suppressed as a file instead of reported as broken. `.5`
+  satisfied the pattern as readily as `.md`.
+
+The first class found that DEFLATES `check`'s flagship number rather than inflating it, which is
+  strictly worse for a gate: an undercount is invisible by construction and reads as health. It hits
+  any vault that numbers its notes — phases, specs, chapters, versioned documents.
+
+The separating rule is that a real extension contains a letter; ".5" and ".61850" differ only in
+  length, so no length bound could tell them apart. The existing 10-character bound and the
+  space-after-the-dot rule are both preserved.
+
+Reference vault: 17 non-note-file suppressions before and after, all genuine .base/.png
+  (hand-audited).
+
+### Testing
+
+- **properties**: Add the known-name invariant and an oracle-backed generator (#133)
+  ([#149](https://github.com/cdcoonce/graphmark/pull/149),
+  [`4cd304f`](https://github.com/cdcoonce/graphmark/commit/4cd304f80da52f2941205986d3b4bb3de783fdab))
+
+Two things, one purpose: make Track F's detector actually detect.
+
+#133's invariant — no link reported `missing` may name a key the resolver already knows (catalog or
+  aliases). Under correct behavior that is impossible, so it is an internal-consistency assertion,
+  not a heuristic: no thresholds, no calibration, no false-positive mode. Asserted over generated
+  vaults, with resolve_aliases=False (where the alias half is vacuous rather than wrong), and with
+  teeth — breaking the lookup while the map is still built must fail it.
+
+The generator, measured. With the alphabet widened to today's four defect classes, reverting
+  #123/#136/#137/#138/#139 one at a time still left the suite GREEN: 0 of 4. Every existing property
+  is a conservation or self-consistency check, and each of those bugs is perfectly self-consistent —
+  #136's fabricated edge really is in the graph. Self-consistency cannot see a wrong answer.
+
+So the generator now carries an oracle: it builds a note, then writes the link FROM it through a
+  transformation Obsidian treats as identity-preserving, so the expected target is known by
+  construction. Plus a negative oracle over names known to be absent (the false-negative half, which
+  no conservation law can see), narrow per-vault name pools so collisions co-occur, and an assertion
+  that an `ambiguous` candidate set is minimal rather than merely non-empty.
+
+Catch rate on the same experiment: 6 of 6, adding #119.
+
+
+## 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.2}/PKG-INFO

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

{graphmark-0.7.0 → graphmark-0.7.2}/docs/ROADMAP.md

@@ -144,6 +144,51 @@ 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.
+
+_Follow-on, same day (#133's slice):_ widening the alphabet was **not enough, and the measurement
+says why.** With the alphabet widened, reverting #123/#136/#137/#138/#139 one at a time left the
+whole property suite green — a catch rate of **0 of 4** on the classes it was widened for. Every
+invariant in that file is a _conservation or self-consistency_ property, and each of those bugs is
+perfectly self-consistent: #136's fabricated edge really is in the graph, so nothing vanishes; a
+BOM'd note simply has no frontmatter; a link the normalizer cannot match is genuinely missing by the
+package's own rules. **Self-consistency cannot see a wrong answer.**
+
+What was missing is an **oracle** — a link whose intended target is known independently of what the
+resolver says. The generator now builds a note first and writes the link _from_ it, through a
+transformation Obsidian treats as identity-preserving (case, `.md`, anchor, alias display, padding,
+NFD/NFC, punctuation swaps, path qualification, ASCII twins of typographic marks), plus a negative
+oracle over names known to be absent. Two further changes were needed to make it bite: narrow
+per-vault name pools, so the collisions that matter actually co-occur, and an assertion that an
+`ambiguous` candidate set is _minimal_, not merely non-empty.
+
+Catch rate on the same experiment: **6 of 6**, adding #119 — the class that started this track.
+
+The generalizable lesson, and the one to carry into future test design here: **a property suite over
+generated input still needs a correct answer to compare against.** Invariants prove the package is
+consistent with itself, which is exactly the thing a systematically wrong resolver also is.
+
+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.2}/pyproject.toml

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

{graphmark-0.7.0 → graphmark-0.7.2}/src/graphmark/cli.py

@@ -42,7 +42,39 @@ def _load(args: argparse.Namespace) -> tuple[VaultGraph, VaultConfig]:
     return graph, config
 
 
+def _reconcile_globals(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
+    """Merge each global's leading and trailing occurrence into one value.
+
+    ``--config``/``--root`` are attached to the top-level parser *and*, under a separate dest, to
+    every subparser, so both ``graphmark --root X stats`` and ``graphmark stats --root X`` work.
+    Trailing-option order is what every comparable CLI accepts and what a user types by reflex — and
+    it is what the README documents, so before this the first command a new user copied errored.
+
+    Repeats with the **same** value are harmless. Two different values are a usage error rather than
+    a silent last-wins: guessing which one the user meant is exactly the kind of quiet wrong answer
+    this tool exists not to give. Both options collect with ``action="append"``, so this covers a
+    repeat *within* one position (``stats --root A --root B``) as well as one across the two —
+    argparse's own last-wins would otherwise swallow the first silently.
+    """
+    for name in ("config", "root"):
+        after = f"{name}_after"
+        # `after` is absent when no subcommand ran at all — argparse never reached a subparser.
+        given = (getattr(args, name) or []) + (getattr(args, after, None) or [])
+        distinct = sorted(set(given))
+        if len(distinct) > 1:
+            parser.error(f"--{name} given more than once with conflicting values: {distinct}")
+        setattr(args, name, distinct[0] if distinct else None)
+        if hasattr(args, after):
+            delattr(args, after)
+
+
 def main() -> None:
+    # Attached to every subparser under a distinct dest, then reconciled: argparse would otherwise
+    # let the subparser's default (None) overwrite a value the top-level parser had already read.
+    trailing_globals = argparse.ArgumentParser(add_help=False)
+    trailing_globals.add_argument("--config", metavar="PATH", dest="config_after", action="append")
+    trailing_globals.add_argument("--root", metavar="PATH", dest="root_after", action="append")
+
     parser = argparse.ArgumentParser(
         prog="graphmark",
         description=(
@@ -51,49 +83,86 @@ def main() -> None:
         ),
     )
     parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
-    parser.add_argument("--config", metavar="PATH", help="TOML config file")
-    parser.add_argument("--root", metavar="PATH", help="Vault root (overrides --config root)")
+    parser.add_argument("--config", metavar="PATH", action="append", help="TOML config file")
+    parser.add_argument(
+        "--root", metavar="PATH", action="append", help="Vault root (overrides --config root)"
+    )
 
     sub = parser.add_subparsers(dest="command", metavar="COMMAND")
 
-    sub.add_parser("stats", help="Aggregate vault stats: notes, edges, orphans, clusters, density")
-    sub.add_parser("orphans", help="Notes with no links in or out (degree 0)")
+    sub.add_parser(
+        "stats",
+        parents=[trailing_globals],
+        help="Aggregate vault stats: notes, edges, orphans, clusters, density",
+    )
+    sub.add_parser(
+        "orphans", parents=[trailing_globals], help="Notes with no links in or out (degree 0)"
+    )
 
-    hubs_p = sub.add_parser("hubs", help="Most-connected notes, by undirected degree")
+    hubs_p = sub.add_parser(
+        "hubs", parents=[trailing_globals], help="Most-connected notes, by undirected degree"
+    )
     hubs_p.add_argument("--n", type=int, default=10, help="How many hubs to return (default: 10)")
 
-    sub.add_parser("clusters", help="Connected components of the link graph, largest first")
-    sub.add_parser("bridges", help="Articulation points: notes whose removal splits the graph")
-    sub.add_parser("siloed", help="Notes reachable from the mainland only through one bridge")
+    sub.add_parser(
+        "clusters",
+        parents=[trailing_globals],
+        help="Connected components of the link graph, largest first",
+    )
+    sub.add_parser(
+        "bridges",
+        parents=[trailing_globals],
+        help="Articulation points: notes whose removal splits the graph",
+    )
+    sub.add_parser(
+        "siloed",
+        parents=[trailing_globals],
+        help="Notes reachable from the mainland only through one bridge",
+    )
 
-    nb_p = sub.add_parser("neighborhood", help="Links in and out of one note")
+    nb_p = sub.add_parser(
+        "neighborhood", parents=[trailing_globals], help="Links in and out of one note"
+    )
     nb_p.add_argument("--note", required=True, help="Vault-relative path, e.g. brain/hub.md")
     nb_p.add_argument(
         "--depth", type=int, default=1, help="1 for direct links, 2 to add two-hop (default: 1)"
     )
 
-    pr_p = sub.add_parser("pagerank", help="PageRank importance ranking over the link graph")
+    pr_p = sub.add_parser(
+        "pagerank",
+        parents=[trailing_globals],
+        help="PageRank importance ranking over the link graph",
+    )
     pr_p.add_argument("--n", type=int, default=10, help="How many notes to return (default: 10)")
     pr_p.add_argument(
         "--alpha", type=float, default=0.85, help="Damping factor in (0, 1) (default: 0.85)"
     )
 
-    exp_p = sub.add_parser("export", help="Export the graph in another format")
+    exp_p = sub.add_parser(
+        "export", parents=[trailing_globals], help="Export the graph in another format"
+    )
     exp_p.add_argument("format", choices=["dot"], help="Output format")
 
-    sub.add_parser("gaps", help="Link-gap suggestions (library-only; see the README)")
+    sub.add_parser(
+        "gaps",
+        parents=[trailing_globals],
+        help="Link-gap suggestions (library-only; see the README)",
+    )
 
     sub.add_parser(
         "links",
+        parents=[trailing_globals],
         help="How every wikilink was classified: counts per reason, plus alias resolutions",
     )
 
     sub.add_parser(
         "check",
+        parents=[trailing_globals],
         help="Gate vault health against the config's [check] thresholds (exit 1 on breach)",
     )
 
     args = parser.parse_args()
+    _reconcile_globals(parser, args)
 
     # Usage errors all exit 2, matching argparse's own convention (and leaving exit 1 free for
     # future domain-level outcomes such as a `check` threshold breach). Help for a missing

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

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import re
 import string
+import unicodedata
 from dataclasses import dataclass, field, replace
+from functools import lru_cache
 from pathlib import Path
 
 from graphmark.config import VaultConfig
@@ -15,15 +17,67 @@ from graphmark.parse import parse_document
 _PUNCT_TABLE = str.maketrans(string.punctuation, " " * len(string.punctuation))
 
 
+def _fold_case(text: str) -> str:
+    """Compose to NFC, then lowercase — the two form-flattening steps, in that order.
+
+    macOS's HFS+/APFS store filenames **decomposed** (NFD: ``é`` is ``e`` + U+0301) while text typed
+    in an editor is **composed** (NFC: a single U+00E9). Without this the two never compare equal
+    and an accented note title is a phantom broken link, which Obsidian resolves fine.
+
+    NFC rather than NFD because it is what editors emit and what the web standardized on; the
+    filesystem's NFD becomes an implementation detail that never escapes the catalog.
+
+    Shared by ``_normalize`` and by path-suffix matching — the one place that does *not* go through
+    ``_normalize`` — so no comparison in this module can be left in the wrong form.
+    """
+    return unicodedata.normalize("NFC", text).lower()
+
+
+@lru_cache(maxsize=4096)
+def _is_foldable(char: str) -> bool:
+    """True for a Unicode punctuation (``P*``) or symbol (``S*``) character."""
+    return unicodedata.category(char)[0] in ("P", "S")
+
+
+def _fold_punctuation(text: str) -> str:
+    """Replace punctuation and symbols with spaces — ASCII **and** non-ASCII.
+
+    ``string.punctuation`` is ASCII-only, so every non-ASCII mark used to survive normalization and
+    then had to be typed byte-for-byte: an em-dash title was unreachable from a typed hyphen, a
+    curly apostrophe from a straight one, ``…`` from ``...``. Folding by Unicode *category* is a
+    superset of the old ASCII table, so pure-ASCII results are unchanged.
+
+    The ASCII table stays the fast path; the per-character category lookup runs only on strings that
+    still hold non-ASCII after it, and is cached. This function runs once per catalog entry and once
+    per link, so it must not become a per-character Python loop over the whole vault.
+
+    Callers must compose to NFC first (``_fold_case``): a decomposed ``é`` is a letter plus a
+    combining mark of category ``Mn``, which this fold correctly leaves alone but which would
+    otherwise leave the accent stranded.
+    """
+    folded = text.translate(_PUNCT_TABLE)
+    if folded.isascii():
+        return folded
+    return "".join(" " if not c.isascii() and _is_foldable(c) else c for c in folded)
+
+
 def _normalize(text: str) -> str:
-    """Lowercase, replace punctuation with spaces, collapse whitespace."""
-    return " ".join(text.lower().translate(_PUNCT_TABLE).split())
+    """Compose to NFC, lowercase, replace punctuation with spaces, collapse whitespace."""
+    return " ".join(_fold_punctuation(_fold_case(text)).split())
 
 
-# A trailing dot plus a short alphanumeric run — a plausible file extension. Deliberately
-# strict so a note title like "v1.2 release notes" (spaces after the dot) is not mistaken
-# for one.
-_FILE_SUFFIX_RE = re.compile(r"\.[A-Za-z0-9]{1,10}$")
+# A trailing dot plus a short alphanumeric run containing at least one letter — a plausible file
+# extension. Deliberately strict in two ways, and both matter:
+#
+# * spaces after the dot disqualify it, so a note title like "v1.2 release notes" is not mistaken
+#   for one;
+# * an all-digit run disqualifies it, so a *numbered* title — "[[Meeting 3.5]]", "[[Phase 2.1]]",
+#   "[[Spec v0.9]]" — is reported as the broken link it is rather than suppressed as a file.
+#
+# The letter requirement is what separates them: ".5" and ".61850" differ only in length, so no
+# length bound could. Suppressing a genuine break *deflates* the vault-health count, which is worse
+# than inflating it — an undercount is invisible and reads as health.
+_FILE_SUFFIX_RE = re.compile(r"\.(?=[A-Za-z0-9]{1,10}$)[A-Za-z0-9]*[A-Za-z][A-Za-z0-9]*$")
 
 
 def _strip_display(display: str) -> str:
@@ -54,6 +108,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 = _fold_case(rel_path)
+    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.
 
@@ -69,9 +141,12 @@ def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
     if not target:
         return []
     if "/" in target:
-        suffix = target.lower() + ".md"
+        suffix = _fold_case(target) + ".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), ()))
 
@@ -168,9 +243,9 @@ class NormalizeResolver:
 
         if "/" in display:
             # Path-suffix resolution: find unique rel_path ending with "display.md"
-            suffix = display.lower() + ".md"
+            suffix = _fold_case(display) + ".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.2}/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.2/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"