graphmark 0.7.2__tar.gz → 0.8.1__tar.gz

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

@@ -1,6 +1,135 @@
 # CHANGELOG
 
 
+## v0.8.1 (2026-07-26)
+
+### Performance Improvements
+
+- **graph**: Index path resolution by filename instead of scanning (#157)
+  ([#160](https://github.com/cdcoonce/graphmark/pull/160),
+  [`84cdd29`](https://github.com/cdcoonce/graphmark/commit/84cdd297a665d93ffa3cbb988c18550ea57f5c94))
+
+Every path-qualified display flattened the catalog and compared against every rel_path. That ceiling
+  was documented and accepted while the branch was rare — most wikilink displays are bare names
+  hitting a dict — but #152 made it the only branch, since every markdown link is path-qualified by
+  construction. blue-book (1120 notes, 10,149 markdown links) took 2.7 s against 0.25 s for the same
+  vault read as wikilinks.
+
+A legal suffix match must consume whole path components, so a candidate's last component always
+  equals the display's last plus ".md". Bucketing by that filename is exactly equivalent to scanning
+  — same matches, same order, same verdicts.
+
+The first attempt was no faster, and profiling rather than guessing found why: `_diagnose` consults
+  the in-scope catalog AND the out-of-scope one for the same display, so a single-slot cache
+  alternated and missed every time — 29,265 index rebuilds for 10,149 links. The cache is now
+  bounded-multi-slot, and it holds each catalog rather than just its id(), so a freed dict cannot
+  have its address reused under a stale index.
+
+blue-book markdown: 2718 ms -> 267 ms (10.2x), now level with wikilink mode. Reference vault 195 ->
+  181 ms. All link counts byte-identical in every mode.
+
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.7.2
+Version: 0.8.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
@@ -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.1}/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.1}/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.1}/pyproject.toml

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

{graphmark-0.7.2 → graphmark-0.8.1}/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.1}/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))
 
@@ -142,12 +144,7 @@ def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
         return []
     if "/" in target:
         suffix = _fold_case(target) + ".md"
-        return sorted(
-            path
-            for paths in catalog.values()
-            for path in paths
-            if _matches_path_suffix(path, suffix)
-        )
+        return sorted(_suffix_matches(suffix, catalog, _CANDIDATE_INDEX))
     return list(catalog.get(_normalize(target), ()))
 
 
@@ -215,25 +212,74 @@ def build_catalog(docs: list[Document]) -> dict[str, list[str]]:
     return catalog
 
 
+class _FilenameIndex:
+    """Catalog paths bucketed by folded filename, so a path-qualified link scans a bucket.
+
+    A legal suffix match must consume whole path components (see ``_matches_path_suffix``), so a
+    candidate's **last** component always equals the display's last component plus ``.md``.
+    Bucketing by that filename is therefore *exactly* equivalent to scanning every path — same
+    matches, same order — while turning an O(N) sweep into a dict lookup over a bucket that is
+    almost always one entry deep.
+
+    This mattered little while path-qualified links were rare: most wikilink displays are bare names
+    hitting the catalog dict directly, which is why the ``O(L·N)`` ceiling was documented and
+    accepted. #152 changed which branch is hot — every markdown link is path-qualified by
+    construction — and a 1120-note vault with 10,149 of them took 2.9 s against 0.3 s for the same
+    vault read as wikilinks.
+
+    Keyed by catalog identity, which is safe because a catalog is invariant for a whole
+    ``VaultGraph.build()``. Each catalog is **held**, not just its ``id()``: without a reference the
+    dict could be freed and a new one allocated at the same address, and the stale index would then
+    answer for it.
+
+    Several slots, not one, and that is load-bearing rather than defensive. ``_diagnose`` consults
+    two different mappings for the same display — the in-scope ``catalog`` and the ``out_of_scope``
+    one — so a single slot alternates between them and misses *every* time. Measured: a single-slot
+    version rebuilt the index 29,265 times for 10,149 links and was no faster than the scan it
+    replaced. The cap keeps this from growing without bound if a caller cycles through catalogs.
+    """
+
+    #: Enough for the two mappings a build alternates between, with room to spare. Small on purpose:
+    #: this holds catalogs alive, so it must not become an unbounded retainer.
+    _MAX_SLOTS = 4
+
+    def __init__(self) -> None:
+        # Insertion-ordered, so the oldest entry is the one evicted.
+        self._slots: dict[int, tuple[dict[str, list[str]], dict[str, list[str]]]] = {}
+
+    def for_catalog(self, catalog: dict[str, list[str]]) -> dict[str, list[str]]:
+        cached = self._slots.get(id(catalog))
+        if cached is not None and cached[0] is catalog:
+            return cached[1]
+
+        buckets: dict[str, list[str]] = {}
+        for paths in catalog.values():
+            for path in paths:
+                buckets.setdefault(_fold_case(path.rsplit("/", 1)[-1]), []).append(path)
+
+        if len(self._slots) >= self._MAX_SLOTS:
+            del self._slots[next(iter(self._slots))]
+        self._slots[id(catalog)] = (catalog, buckets)
+        return buckets
+
+
+def _suffix_matches(suffix: str, catalog: dict[str, list[str]], index: _FilenameIndex) -> list[str]:
+    """Every rel_path that ``suffix`` (a folded ``folder/note.md``) names, in flatten order."""
+    bucket = index.for_catalog(catalog).get(suffix.rsplit("/", 1)[-1], ())
+    return [path for path in bucket if _matches_path_suffix(path, suffix)]
+
+
+#: Shared by ``candidates_for``, which takes a catalog rather than a resolver and so cannot reach
+#: the resolver's own index. One index per process is enough — both callers see the same catalog
+#: object for the length of a build, and a different catalog simply re-keys it.
+_CANDIDATE_INDEX = _FilenameIndex()
+
+
 class NormalizeResolver:
     """Resolves wikilink displays via normalized basename, with path-suffix fallback."""
 
     def __init__(self) -> None:
-        # Cache the flattened path list per catalog identity. catalog is invariant for a whole
-        # VaultGraph.build(), so folder-style links reuse one flatten instead of rebuilding it
-        # on every call. Keyed by id() and single-slot: a new catalog evicts the previous.
-        self._flat_cache_id: int | None = None
-        self._flat_cache: list[str] | None = None
-
-    @staticmethod
-    def _compute_flat(catalog: dict[str, list[str]]) -> list[str]:
-        return [p for paths in catalog.values() for p in paths]
-
-    def _flatten_paths(self, catalog: dict[str, list[str]]) -> list[str]:
-        if self._flat_cache_id != id(catalog) or self._flat_cache is None:
-            self._flat_cache = self._compute_flat(catalog)
-            self._flat_cache_id = id(catalog)
-        return self._flat_cache
+        self._index = _FilenameIndex()
 
     def resolve(self, display: str, catalog: dict[str, list[str]]) -> str | None:
         # Alias ("Note|alias"), anchor ("Note#Section") and an explicit ".md" extension all name
@@ -242,10 +288,11 @@ class NormalizeResolver:
         display = _strip_display(display)
 
         if "/" in display:
-            # Path-suffix resolution: find unique rel_path ending with "display.md"
+            # Path-suffix resolution: find unique rel_path ending with "display.md". Note that an
+            # exact whole-path hit cannot short-circuit — "work/Tasks" names both "work/Tasks.md"
+            # and "a/work/Tasks.md", and the honest answer there is to decline.
             suffix = _fold_case(display) + ".md"
-            all_paths = self._flatten_paths(catalog)
-            matches = [p for p in all_paths if _matches_path_suffix(p, suffix)]
+            matches = _suffix_matches(suffix, catalog, self._index)
             return matches[0] if len(matches) == 1 else None
 
         # Bare-link resolution: normalize and look up in catalog
@@ -463,6 +510,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 +668,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 +695,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.1}/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.7.2 → graphmark-0.8.1}/tests/test_graph.py

@@ -91,19 +91,15 @@ class TestNormalizeResolver:
         assert self.resolver.resolve("brain/alpha", catalog) == "brain/alpha.md"
         assert self.resolver.resolve("work/gamma", catalog) == "work/gamma.md"
 
-    def test_flatten_runs_once_per_catalog(self, monkeypatch):
+    def test_the_path_index_is_built_once_per_catalog(self):
+        # Was written against the flatten this replaced (#157); the property is the same one and
+        # still worth holding — the O(n) precompute must not run per link.
         catalog = self._catalog("brain/alpha.md", "personal/beta.md")
-        calls = {"n": 0}
-        real_compute = NormalizeResolver._compute_flat
-
-        def counting_compute(cat):
-            calls["n"] += 1
-            return real_compute(cat)
-
-        monkeypatch.setattr(self.resolver, "_compute_flat", counting_compute)
+        self.resolver.resolve("brain/alpha", catalog)
+        buckets = self.resolver._index.for_catalog(catalog)
         for _ in range(5):
             self.resolver.resolve("brain/alpha", catalog)
-        assert calls["n"] == 1  # the O(n) flatten runs once, reused for the rest
+        assert self.resolver._index.for_catalog(catalog) is buckets
 
     def test_new_catalog_triggers_reflatten(self):
         cat1 = self._catalog("brain/alpha.md")