graphmark 0.7.2__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,107 @@
 # CHANGELOG
 
 
+## v0.8.0 (2026-07-26)
+
+### Documentation
+
+- Document link_syntax and close the markdown non-goal
+  ([#158](https://github.com/cdcoonce/graphmark/pull/158),
+  [`5523fe3`](https://github.com/cdcoonce/graphmark/commit/5523fe31b548eb5e94001515ab8e8adb7c084849))
+
+* docs: document link_syntax and close the markdown non-goal
+
+README gains a Link syntax section — the config key, the warning, and the one thing a user must
+  understand: a wikilink NAMES a note (ambiguous when two share it) while a markdown link is a PATH
+  RELATIVE TO THE LINKING NOTE (never ambiguous for the same reason). Different resolution regimes,
+  not two spellings.
+
+Roadmap's non-goal narrowed to Logseq, recording that #152 was the "on demand" trigger the clause
+  reserved — and recording what it did not do: no basename fallback, because silently trying a
+  second rule when the first fails is the shape of #136. The dialect question is #156 with its
+  measurement.
+
+* fix(test): a console block's output is not a command
+
+The README-example extractor treated every line starting with "graphmark " as an invocation,
+  including output. Adding the link-syntax section wrapped the #151 warning onto a second line
+  beginning "graphmark only reads ..." — collected as a command and run.
+
+In a `console` block, `$ ` marks input and everything else is output, so the prefix is now required
+  there; `bash` blocks keep bare lines. Caught by the suite it belongs to, on its author's own
+  input.
+
+- Second corpus run — the null result and the extractor blind spot
+  ([#153](https://github.com/cdcoonce/graphmark/pull/153),
+  [`475b111`](https://github.com/cdcoonce/graphmark/commit/475b1112767bb9ca92d82cb0d391bf20543759c4))
+
+Repeated the corpus study after #123/#136/#137/#138/#139 shipped, to ask whether those fixes move
+  any real number and whether there is demand for the link-syntax work the roadmap defers. Six
+  vaults; two overlap the first run.
+
+The five fixes moved NOTHING — arkalim and kepano reproduce the first run's percentages to the
+  decimal. Recorded rather than buried: correctness-by-inspection has outrun what this corpus can
+  corroborate.
+
+The finding that was not theoretical: lyz-code/blue-book, 1120 notes, carries 11,198 markdown-style
+  [text](note.md) links (99% targeting a real note) and extracts to ZERO edges. Every note an
+  orphan, and `check` looks nearly healthy because those links were never extracted and so are not
+  unresolved.
+
+That is a third named limit of the Track F thesis: the conservation law sums over what the EXTRACTOR
+  produced, so a syntax it does not know is invisible to it by construction. The accounting is
+  auditable only within the universe the extractor defines. Filed as #151 (warn) and #152 (the
+  markdown-syntax decision).
+
+### Features
+
+- Read markdown-style [text](note.md) links, config-gated (#152)
+  ([#155](https://github.com/cdcoonce/graphmark/pull/155),
+  [`6716a38`](https://github.com/cdcoonce/graphmark/commit/6716a3845b15665190f03f1bce3605a2927322e2))
+
+The roadmap reserved alternate link-syntax adapters for "on demand"; the second corpus run supplied
+  the demand — lyz-code/blue-book, 1120 notes, 10,149 markdown-style links, zero extracted edges.
+
+Four decisions, all reversible in config:
+
+1. `link_syntax = "wikilink" | "markdown" | "both"`, defaulting to "wikilink", so every existing
+  vault, every frozen fixture and the reference vault stay byte-identical. An unknown value fails
+  loudly — a typo would otherwise produce an empty graph, the exact failure #151 exists to surface.
+  2. Resolution is RELATIVE TO THE LINKING NOTE, which is genuinely new: a markdown target is a
+  path, not a name. Rather than change the `Resolver` protocol — which never receives the source
+  note, and which the roadmap forbids redesigning — the target is normalized into a vault-relative
+  path before diagnosis, where the existing path branch resolves it exactly. 3. No new frozen
+  fixture: the oracle is wikilink-only and regenerating it is a human's call (Track B). Hand-written
+  assertions instead. 4. A target escaping the vault root is `missing` — not resolved, not an error.
+
+Relative is default markdown semantics (CommonMark, mkdocs, GitHub) and NOT the wikilink rule.
+  blue-book resolves 5.8% that way against 92.7% by basename-anywhere, because it runs the
+  mkdocs-autolinks plugin. That dialect is a separate decision, not a fallback slipped in here —
+  silently trying a second rule when the first fails is how a link resolves to the wrong note.
+
+The #151 warning is suppressed once markdown links are actually read.
+
+- **graph**: Warn when the vault's links are in a syntax graphmark cannot read (#151)
+  ([#154](https://github.com/cdcoonce/graphmark/pull/154),
+  [`d94ae63`](https://github.com/cdcoonce/graphmark/commit/d94ae63e7a789fabdb420423eaeaee8e771eb2a7))
+
+graphmark reported a confidently EMPTY graph for a densely linked vault, with nothing to say it had
+  seen none of the links. Measured on lyz-code/blue-book: 1120 notes, 11,198 markdown-style
+  [text](note.md) links (99% targeting a note that exists), 0 extracted edges. Every note an orphan,
+  no clusters, no hubs, uniform PageRank — and `check` looks nearly healthy, because links that were
+  never extracted are not `unresolved`.
+
+The conservation law from #124 cannot catch this: it sums over what the EXTRACTOR produced, so a
+  syntax the extractor does not know sits outside the universe being counted. The buckets balance
+  perfectly at 39 while 11,198 links go unseen.
+
+The test is relational, not calibrated — it fires only when the unread syntax strictly outnumbers
+  the read one. No threshold to tune, no false-positive mode, and the reference vault's
+  17-against-6226 can never trip it. Same discipline as #133's assertion.
+
+Warning only: stderr, one line, and it touches no count, no metric and no verdict.
+
+
 ## v0.7.2 (2026-07-25)
 
 ### Bug Fixes

{graphmark-0.7.2 → graphmark-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.7.2
+Version: 0.8.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
@@ -111,6 +111,32 @@ notice the tool is wrong about your vault.
 The same block appears in `check`'s report under `links`, as context for the verdict. It never
 changes the verdict.
 
+## Link syntax
+
+graphmark reads `[[wikilinks]]` by default. A vault written in markdown link syntax —
+`[text](note.md)`, what most non-Obsidian markdown gardens use — would otherwise produce an empty
+graph, so set `link_syntax`:
+
+```toml
+root = "."
+link_syntax = "both"   # "wikilink" (default) | "markdown" | "both"
+```
+
+The two resolve differently, and the difference is not cosmetic:
+
+- a **wikilink** names a note — `[[Note]]` finds `Note.md` anywhere in the vault, and two notes with
+  that name make it ambiguous;
+- 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.
+
+If your links are in a syntax graphmark is not reading, it says so on stderr rather than reporting a
+confidently empty graph:
+
+```console
+graphmark: warning: 39 wikilinks extracted but 10149 markdown-style [](.md) links found;
+graphmark only reads [[wikilinks]] — this graph is probably not your vault
+```
+
 ## `graphmark check` — vault health as a CI gate
 
 Declare thresholds in the config's `[check]` table, then run `graphmark check` as a build step. It

{graphmark-0.7.2 → graphmark-0.8.0}/README.md

@@ -83,6 +83,32 @@ notice the tool is wrong about your vault.
 The same block appears in `check`'s report under `links`, as context for the verdict. It never
 changes the verdict.
 
+## Link syntax
+
+graphmark reads `[[wikilinks]]` by default. A vault written in markdown link syntax —
+`[text](note.md)`, what most non-Obsidian markdown gardens use — would otherwise produce an empty
+graph, so set `link_syntax`:
+
+```toml
+root = "."
+link_syntax = "both"   # "wikilink" (default) | "markdown" | "both"
+```
+
+The two resolve differently, and the difference is not cosmetic:
+
+- a **wikilink** names a note — `[[Note]]` finds `Note.md` anywhere in the vault, and two notes with
+  that name make it ambiguous;
+- 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.
+
+If your links are in a syntax graphmark is not reading, it says so on stderr rather than reporting a
+confidently empty graph:
+
+```console
+graphmark: warning: 39 wikilinks extracted but 10149 markdown-style [](.md) links found;
+graphmark only reads [[wikilinks]] — this graph is probably not your vault
+```
+
 ## `graphmark check` — vault health as a CI gate
 
 Declare thresholds in the config's `[check]` table, then run `graphmark check` as a build step. It

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

@@ -185,6 +185,19 @@ The generalizable lesson, and the one to carry into future test design here: **a
 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.
 
+_Second corpus run, same day (see `docs/corpus-study.md`):_ a **third** named limit, and a null
+result. The null result first — the five fixes above moved **no** third-party number; the two vaults
+overlapping the first run reproduce it to the decimal. They are correct and pinned, but against real
+data they are theoretical, joining #123 there.
+
+The limit: `lyz-code/blue-book` (1120 notes) carries **11,198 markdown-style `[text](note.md)` links,
+99% of them targeting a real note**, and graphmark extracts **zero**. Every note an orphan, and
+`check` looks nearly healthy because those links were never extracted and so are not *unresolved*.
+The conservation law sums over what the **extractor** produced — so a link syntax the extractor does
+not know is invisible to it by construction. **The accounting is auditable only within the universe
+the extractor defines.** Filed as #151 (warn) and #152 (the markdown-syntax decision — the "on
+demand" trigger the non-goals list reserved).
+
 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.
@@ -224,8 +237,13 @@ Evaluated against the ecosystem and dropped for zero consumer pull; do not re-li
 - Betweenness centrality, Louvain/Leiden community detection.
 - CSV/GML/Cypher export; incremental/cached builds; any LLM "propose" pass.
 - MCP server or retrieval/search surface.
-- Alternate link-syntax adapters (Logseq, `[](.)` markdown) — the pluggable interfaces exist so
-  these _can_ be added on demand; do not build them speculatively.
+- Alternate link-syntax adapters (Logseq) — the pluggable interfaces exist so these _can_ be added
+  on demand; do not build them speculatively. **Markdown `[text](note.md)` links SHIPPED 2026-07-25**
+  (#152) — the second corpus run supplied the demand this clause reserved: a 1120-note vault with
+  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.
 - 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.7.2 → graphmark-0.8.0}/pyproject.toml

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

{graphmark-0.7.2 → graphmark-0.8.0}/src/graphmark/config.py

@@ -11,6 +11,10 @@ import tomllib
 from dataclasses import dataclass, field, fields
 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"})
+
 
 @dataclass(frozen=True)
 class CheckPolicy:
@@ -47,6 +51,12 @@ class VaultConfig:
     # 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
+    #: Which link syntax to read. ``"wikilink"`` (the default) is Obsidian's ``[[Note]]`` and is
+    #: 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.
+    link_syntax: str = "wikilink"
     check: CheckPolicy = field(default_factory=CheckPolicy)
 
     def __post_init__(self) -> None:
@@ -54,6 +64,12 @@ class VaultConfig:
         # obscure AttributeError on the first Path operation.
         if not isinstance(self.root, Path):
             self.root = Path(self.root)
+        # Fail loudly rather than silently reading nothing: a typo here would produce an empty
+        # graph, which is exactly the failure #151 exists to make visible.
+        if self.link_syntax not in LINK_SYNTAXES:
+            raise ValueError(
+                f"link_syntax must be one of {sorted(LINK_SYNTAXES)}, got {self.link_syntax!r}"
+            )
 
 
 def _parse_check(data: dict, path: Path) -> CheckPolicy:
@@ -122,5 +138,6 @@ def load_config(path: str | Path, *, root_override: str | Path | None = None) ->
         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)),
+        link_syntax=data.get("link_syntax", "wikilink"),
         check=_parse_check(data, path),
     )

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

@@ -2,17 +2,19 @@
 
 from __future__ import annotations
 
+import posixpath
 import re
 import string
+import sys
 import unicodedata
 from dataclasses import dataclass, field, replace
 from functools import lru_cache
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 
 from graphmark.config import VaultConfig
 from graphmark.interfaces import LinkExtractor, Resolver
 from graphmark.model import Document
-from graphmark.parse import parse_document
+from graphmark.parse import MarkdownLinkExtractor, count_markdown_links, parse_document
 
 _PUNCT_TABLE = str.maketrans(string.punctuation, " " * len(string.punctuation))
 
@@ -463,6 +465,68 @@ 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``.
+
+    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
+    *where the link is* — information the ``Resolver`` protocol never receives, and which the
+    roadmap forbids adding by redesigning that boundary.
+
+    So the dependence is resolved here instead, before diagnosis: the target is normalized against
+    the linking note's folder into a full vault-relative path, and the existing path branch of the
+    resolver then matches it exactly. ``Resolver`` is untouched and still answers "what does this
+    name?" with no notion of a source.
+
+    Relative is the **default markdown semantics** (CommonMark, mkdocs, GitHub) and deliberately
+    not the wikilink rule. Measured on `lyz-code/blue-book`: 5.8% of its links resolve this way
+    against 92.7% by basename-anywhere, because it runs the `mkdocs-autolinks` plugin. That dialect
+    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 —
+    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.
+    """
+    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".
+    if normalized == ".." or normalized.startswith("../"):
+        return None
+    return normalized
+
+
+def _warn_if_unread_syntax_dominates(docs: list[Document], extracted: int) -> None:
+    """Warn once when the vault's links are mostly in a syntax graphmark does not read.
+
+    graphmark extracts ``[[wikilinks]]`` only. A vault written in markdown link syntax therefore
+    produces a confidently *empty* graph — every note an orphan, no clusters, no hubs, uniform
+    PageRank — with nothing to tell the user that none of their links were seen. Worse, ``check``
+    looks nearly healthy, because links that were never extracted are not ``unresolved``.
+
+    Measured on a real 1120-note vault: 11,198 markdown-style links, 99% of them targeting a note
+    that exists, and 0 extracted edges.
+
+    The test is **relational, not calibrated** — it fires only when the unread syntax strictly
+    outnumbers the read one. There is no threshold to tune and no false-positive mode; a vault with
+    a handful of stray markdown links among thousands of wikilinks (the reference vault: 17 against
+    6226) can never trip it. Same discipline as #133's assertion, and the reason this is a warning
+    rather than anything that touches a count or a verdict.
+
+    stderr only, so stdout stays pipeable JSON — as ``links_summary_line`` and ``breach_lines``
+    already do.
+    """
+    unread = sum(count_markdown_links(doc.text) for doc in docs)
+    if unread <= extracted:
+        return
+    print(
+        f"graphmark: warning: {extracted} wikilinks extracted but {unread} markdown-style "
+        f"[](.md) links found; graphmark only reads [[wikilinks]] — this graph is probably "
+        f"not your vault",
+        file=sys.stderr,
+    )
+
+
 class VaultGraph:
     """Built graph: all nodes plus resolved out/back adjacency.
 
@@ -559,8 +623,24 @@ class VaultGraph:
         # is reported rather than absent — "0 alias-resolved" is a finding, not a non-event.
         link_counts: dict[str, int] = dict.fromkeys(DIAGNOSIS_REASONS, 0)
         alias_resolved = 0
+        # Which syntaxes to read. Composed rather than swapped, because the two need different
+        # 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")
+        md_extractor = MarkdownLinkExtractor() if read_markdown else None
+
         for doc in docs:
-            for display in extractor.extract(doc.text):
+            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)
+                    # 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.
+                    displays.append(resolved if resolved is not None else target)
+
+            for display in displays:
                 d = _diagnose(display, catalog, out_of_scope, resolver, aliases)
                 link_counts[d.reason] += 1
                 if d.via == "alias":
@@ -570,6 +650,9 @@ class VaultGraph:
                 elif d.target is not None and d.target != doc.rel_path:
                     out_links[doc.rel_path].add(d.target)
 
+        if not read_markdown:
+            _warn_if_unread_syntax_dominates(docs, sum(link_counts.values()))
+
         for src, targets in out_links.items():
             for dst in targets:
                 back_links[dst].add(src)

{graphmark-0.7.2 → graphmark-0.8.0}/src/graphmark/parse.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import re
 import sys
 from pathlib import Path
+from urllib.parse import unquote
 
 from graphmark.model import Document
 
@@ -93,6 +94,33 @@ def _parse_frontmatter(raw: str) -> dict:
     return result
 
 
+#: A markdown-style link to a local markdown file: ``[text](note.md)`` or
+#: ``[text](../a/b.md#Anchor)``.
+#: Not an image (``![...]``) and not an absolute URL — a link to somebody's README on the web is not
+#: a link into this vault. Deliberately narrow: this counts a *signal*, so a false positive here
+#: would produce a warning about nothing.
+_MD_LINK_RE = re.compile(r"(?<!!)\[[^\]]*\]\((?!\w+:)([^)\s]+?\.md)(?:#[^)]*)?\)")
+
+
+def count_markdown_links(text: str) -> int:
+    """How many ``[text](note.md)`` links the text holds — a syntax graphmark does not read.
+
+    graphmark extracts ``[[wikilinks]]`` only, so a vault written in markdown link syntax produces
+    an empty graph with no indication that anything was missed: every note an orphan, no clusters,
+    and a `check` that looks healthy because links which were never extracted are not *unresolved*.
+
+    The conservation law in ``VaultGraph.build`` cannot see this — it sums over what the extractor
+    produced, so a syntax the extractor does not know sits outside the universe being counted. This
+    function exists to make that universe's edge visible; it feeds a warning and nothing else.
+
+    Code spans and fenced blocks are skipped, exactly as wikilink extraction skips them: a
+    documented example is not a link.
+    """
+    text = _strip_fenced_blocks(text)
+    text = _INLINE_CODE_RE.sub("", text)
+    return len(_MD_LINK_RE.findall(text))
+
+
 class WikilinkExtractor:
     """Extracts raw wikilink displays from note text, excluding code spans."""
 
@@ -102,6 +130,27 @@ class WikilinkExtractor:
         return _WIKILINK_RE.findall(text)
 
 
+class MarkdownLinkExtractor:
+    """Extracts ``[text](note.md)`` targets — the syntax non-Obsidian markdown vaults use.
+
+    Returns the **target**, not the display text, and without its anchor: unlike a wikilink, where
+    the visible text names the note, here the parenthesized path is the only thing that identifies
+    it. The display text is prose and never resolves to anything.
+
+    Percent-encoding is decoded, because markdown encodes spaces (``my%20note.md``) while the vault
+    stores them literally — a link no editor would consider broken.
+
+    The returned target is **relative to the linking note**, which callers must resolve; this class
+    cannot, since ``extract`` sees text and never learns which note it came from. See
+    ``VaultGraph.build``.
+    """
+
+    def extract(self, text: str) -> list[str]:
+        text = _strip_fenced_blocks(text)
+        text = _INLINE_CODE_RE.sub("", text)
+        return [unquote(target) for target in _MD_LINK_RE.findall(text)]
+
+
 def parse_document(path: Path, root: Path) -> Document:
     """Parse a markdown note into a Document, splitting YAML frontmatter from body.
 

graphmark-0.8.0/tests/test_markdown_links.py

@@ -0,0 +1,155 @@
+"""Markdown-style `[text](note.md)` links, config-gated (#152).
+
+The roadmap lists alternate link-syntax adapters under non-goals with a precise escape hatch — "the
+pluggable interfaces exist so these _can_ be added on demand; do not build them speculatively." The
+second corpus run supplied the demand: `lyz-code/blue-book`, 1120 notes, 11,198 markdown-style links
+(99% targeting a real note), zero extracted edges.
+
+Four decisions this encodes, all reversible in config:
+
+1. **Selection** is `link_syntax = "wikilink" | "markdown" | "both"`, defaulting to `"wikilink"`.
+   Every existing vault, every frozen fixture and the reference vault are byte-identical untouched.
+2. **Resolution is relative to the linking note**, which is genuinely new: a markdown target is a
+   path, not a name. Rather than change the `Resolver` protocol — which never receives the source
+   note, and which the roadmap forbids redesigning — the target is normalized into a vault-relative
+   path *before* diagnosis, where the existing path branch resolves it exactly.
+3. **No new frozen fixture.** The oracle is wikilink-only and regenerating it is a human's call
+   (Track B); these are hand-written assertions instead.
+4. **A target that escapes the vault root is `missing`**, not resolved and not an error.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph
+from graphmark.parse import MarkdownLinkExtractor, 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 TestExtractor:
+    def test_extracts_a_relative_target(self):
+        assert MarkdownLinkExtractor().extract("[the note](other.md)") == ["other.md"]
+
+    def test_keeps_the_target_not_the_display_text(self):
+        assert MarkdownLinkExtractor().extract("[Some Title](a/b.md)") == ["a/b.md"]
+
+    def test_drops_an_anchor(self):
+        assert MarkdownLinkExtractor().extract("[x](note.md#Section)") == ["note.md"]
+
+    def test_ignores_images_urls_and_non_markdown_targets(self):
+        text = "![i](c.png) [u](https://x.com/a.md) [p](doc.pdf) [[Wiki]]"
+        assert MarkdownLinkExtractor().extract(text) == []
+
+    def test_ignores_code_spans_and_fences(self):
+        assert MarkdownLinkExtractor().extract("`[a](n.md)`\n```\n[b](n.md)\n```\n") == []
+
+    def test_decodes_percent_encoding(self):
+        # Real markdown encodes spaces; the vault stores them literally.
+        assert MarkdownLinkExtractor().extract("[x](my%20note.md)") == ["my note.md"]
+
+
+class TestDefaultIsUnchanged:
+    def test_markdown_links_are_ignored_by_default(self, tmp_path):
+        _write(tmp_path, "a.md", "[one](b.md)\n")
+        _write(tmp_path, "b.md")
+        graph = _build(tmp_path)
+        assert graph.out_links["a.md"] == set()
+        assert sum(graph.link_counts.values()) == 0
+
+    def test_wikilinks_still_work_in_markdown_mode_only_if_asked(self, tmp_path):
+        _write(tmp_path, "a.md", "[[b]]\n")
+        _write(tmp_path, "b.md")
+        assert _build(tmp_path, link_syntax="markdown").out_links["a.md"] == set()
+        assert _build(tmp_path, link_syntax="both").out_links["a.md"] == {"b.md"}
+
+
+class TestRelativeResolution:
+    def test_a_sibling_target_resolves(self, tmp_path):
+        _write(tmp_path, "docs/a.md", "[one](b.md)\n")
+        _write(tmp_path, "docs/b.md")
+        assert _build(tmp_path, link_syntax="markdown").out_links["docs/a.md"] == {"docs/b.md"}
+
+    def test_a_parent_relative_target_resolves(self, tmp_path):
+        _write(tmp_path, "docs/deep/a.md", "[one](../other/b.md)\n")
+        _write(tmp_path, "docs/other/b.md")
+        graph = _build(tmp_path, link_syntax="markdown")
+        assert graph.out_links["docs/deep/a.md"] == {"docs/other/b.md"}
+
+    def test_an_explicit_dot_slash_resolves(self, tmp_path):
+        _write(tmp_path, "docs/a.md", "[one](./b.md)\n")
+        _write(tmp_path, "docs/b.md")
+        assert _build(tmp_path, link_syntax="markdown").out_links["docs/a.md"] == {"docs/b.md"}
+
+    def test_the_same_name_in_two_folders_does_not_collide(self, tmp_path):
+        # The point of relative resolution: a bare name is NOT ambiguous here, because the
+        # linking note's folder decides. Under wikilink rules this same pair is ambiguous.
+        _write(tmp_path, "one/a.md", "[x](n.md)\n")
+        _write(tmp_path, "one/n.md")
+        _write(tmp_path, "two/n.md")
+        graph = _build(tmp_path, link_syntax="markdown")
+        assert graph.out_links["one/a.md"] == {"one/n.md"}
+        assert graph.link_counts["ambiguous"] == 0
+
+    def test_a_target_escaping_the_vault_is_missing(self, tmp_path):
+        _write(tmp_path, "a.md", "[out](../outside.md)\n")
+        graph = _build(tmp_path, link_syntax="markdown")
+        assert graph.link_counts["missing"] == 1
+        assert graph.out_links["a.md"] == set()
+
+    def test_a_target_that_does_not_exist_is_missing(self, tmp_path):
+        _write(tmp_path, "a.md", "[gone](nowhere.md)\n")
+        assert _build(tmp_path, link_syntax="markdown").link_counts["missing"] == 1
+
+    def test_a_self_link_is_not_an_edge(self, tmp_path):
+        _write(tmp_path, "a.md", "[self](a.md)\n")
+        graph = _build(tmp_path, link_syntax="markdown")
+        assert graph.out_links["a.md"] == set()
+        assert graph.link_counts["resolved"] == 1
+
+
+class TestBothModes:
+    def test_both_syntaxes_are_counted_and_conserved(self, tmp_path):
+        _write(tmp_path, "a.md", "[[b]]\n[one](b.md)\n[gone](nope.md)\n")
+        _write(tmp_path, "b.md")
+        graph = _build(tmp_path, link_syntax="both")
+        assert sum(graph.link_counts.values()) == 3
+        assert graph.link_counts["resolved"] == 2
+        assert graph.link_counts["missing"] == 1
+        assert graph.out_links["a.md"] == {"b.md"}
+
+    def test_the_unread_syntax_warning_is_silent_once_markdown_is_read(self, tmp_path, capsys):
+        _write(tmp_path, "a.md", "[1](b.md)\n[2](b.md)\n[3](b.md)\n")
+        _write(tmp_path, "b.md")
+        _build(tmp_path, link_syntax="both")
+        assert capsys.readouterr().err == ""
+
+
+class TestConfig:
+    def test_an_unknown_syntax_is_rejected(self, tmp_path):
+        _write(tmp_path, "a.md")
+        try:
+            _build(tmp_path, link_syntax="logseq")
+        except ValueError as e:
+            assert "link_syntax" in str(e)
+        else:
+            raise AssertionError("an unknown link_syntax must fail loudly")
+
+    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 = "both"\n', encoding="utf-8")
+        assert load_config(cfg).link_syntax == "both"

{graphmark-0.7.2 → graphmark-0.8.0}/tests/test_readme_examples.py

@@ -44,14 +44,21 @@ def _readme_commands() -> list[str]:
     # non-greedy match begin at a *closing* fence and swallow prose between blocks, which silently
     # yields zero commands — caught by the guard test below rather than shipping a vacuous suite.
     blocks = re.findall(
-        r"^```(?:bash|console|sh)\n(.*?)^```", README.read_text(), re.DOTALL | re.MULTILINE
+        r"^```(bash|console|sh)\n(.*?)^```", README.read_text(), re.DOTALL | re.MULTILINE
     )
     commands = []
-    for block in blocks:
+    for lang, block in blocks:
         for line in block.splitlines():
-            line = line.removeprefix("$ ").strip()
-            if line.startswith("graphmark "):
-                commands.append(line)
+            # In a `console` block, `$ ` marks input and everything else is *output* — which is why
+            # the prefix is required there. Without that rule a wrapped warning line beginning
+            # "graphmark only reads ..." is collected as a command and run, which is exactly what
+            # happened when the link-syntax section was added.
+            if lang == "console":
+                if not line.startswith("$ "):
+                    continue
+                line = line.removeprefix("$ ")
+            if line.strip().startswith("graphmark "):
+                commands.append(line.strip())
     return commands
 
 

graphmark-0.8.0/tests/test_unread_syntax.py

@@ -0,0 +1,111 @@
+"""Warn when the vault's links are in a syntax graphmark does not read (#151).
+
+graphmark can report a confidently empty graph for a densely linked vault. Measured on
+`lyz-code/blue-book`: 1120 notes, 11,198 markdown-style `[text](note.md)` links (99% of them
+targeting a note that exists), and **zero** extracted edges. Every note an orphan, and `check` looks
+nearly healthy — `max_unresolved_links` sees 38, because links that were never extracted are not
+*unresolved*.
+
+The conservation law from #124 cannot catch this: it sums over what the extractor produced, so a
+syntax the extractor does not know is invisible to it by construction. The buckets balance perfectly
+at 39 while 11,198 links sit outside the universe being counted.
+
+The signal is deliberately relational, not calibrated — it fires only when the unread syntax
+*outnumbers* the read one. No threshold to tune and no false-positive mode, in the same spirit as
+#133's assertion.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from graphmark.config import VaultConfig
+from graphmark.graph import NormalizeResolver, VaultGraph
+from graphmark.parse import WikilinkExtractor, count_markdown_links
+
+
+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 TestCounting:
+    def test_counts_a_relative_markdown_link(self):
+        assert count_markdown_links("see [the note](other.md) here") == 1
+
+    def test_counts_a_path_and_an_anchor(self):
+        assert count_markdown_links("[a](../deep/note.md) [b](note.md#Section)") == 2
+
+    def test_ignores_absolute_urls(self):
+        text = "[spec](https://example.com/docs/README.md) [m](mailto:x@y.md)"
+        assert count_markdown_links(text) == 0
+
+    def test_ignores_images_and_non_markdown_targets(self):
+        assert count_markdown_links("![img](chart.png) [pdf](doc.pdf) [c](board.canvas)") == 0
+
+    def test_ignores_wikilinks(self):
+        assert count_markdown_links("[[Note]] and [[folder/Note.md]]") == 0
+
+    def test_ignores_a_link_inside_a_code_fence(self):
+        # Same exclusion the wikilink extractor applies; a documented example is not a link.
+        assert count_markdown_links("```\n[a](note.md)\n```\n") == 0
+
+    def test_ignores_a_link_inside_an_inline_code_span(self):
+        assert count_markdown_links("`[a](note.md)`") == 0
+
+
+class TestWarning:
+    def test_warns_when_the_unread_syntax_outnumbers_the_read_one(self, tmp_path, capsys):
+        _write(tmp_path, "a.md", "[one](b.md)\n[two](c.md)\n[three](b.md)\n[[b]]\n")
+        _write(tmp_path, "b.md")
+        _write(tmp_path, "c.md")
+        _build(tmp_path)
+        captured = capsys.readouterr()
+        assert captured.out == "", "the JSON surface must stay pipeable"
+        assert "3" in captured.err and "markdown" in captured.err.lower()
+        assert captured.err.count("warning") == 1, "exactly one line, not one per note"
+
+    def test_is_silent_when_wikilinks_dominate(self, tmp_path, capsys):
+        # The reference vault's real ratio: a handful of markdown links against thousands of
+        # wikilinks. This must never fire there.
+        body = "[[b]]\n" * 20 + "[stray](b.md)\n"
+        _write(tmp_path, "a.md", body)
+        _write(tmp_path, "b.md")
+        _build(tmp_path)
+        assert capsys.readouterr().err == ""
+
+    def test_is_silent_with_no_markdown_links_at_all(self, tmp_path, capsys):
+        _write(tmp_path, "a.md", "[[b]]\n")
+        _write(tmp_path, "b.md")
+        _build(tmp_path)
+        assert capsys.readouterr().err == ""
+
+    def test_is_silent_on_an_empty_vault(self, tmp_path, capsys):
+        _write(tmp_path, "a.md", "no links here\n")
+        _build(tmp_path)
+        assert capsys.readouterr().err == ""
+
+    def test_an_equal_count_does_not_warn(self, tmp_path, capsys):
+        # Strictly greater, so the signal cannot fire on a tie — deliberately conservative.
+        _write(tmp_path, "a.md", "[[b]]\n[one](b.md)\n")
+        _write(tmp_path, "b.md")
+        _build(tmp_path)
+        assert capsys.readouterr().err == ""
+
+
+class TestNoBehaviorChange:
+    def test_the_warning_changes_no_count_and_no_edge(self, tmp_path, capsys):
+        _write(tmp_path, "a.md", "[one](b.md)\n[two](b.md)\n[[b]]\n")
+        _write(tmp_path, "b.md")
+        graph = _build(tmp_path)
+        capsys.readouterr()
+        assert graph.link_counts["resolved"] == 1
+        assert sum(graph.link_counts.values()) == 1, "markdown links are counted nowhere"
+        assert graph.out_links["a.md"] == {"b.md"}