graphmark 0.7.1__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,216 @@
 # 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
+
+- **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

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

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

@@ -163,6 +163,41 @@ Two things this says about the track:
   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.
+
+_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.
@@ -202,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.1 → graphmark-0.8.0}/pyproject.toml

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

{graphmark-0.7.1 → graphmark-0.8.0}/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.1 → 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),
     )