graphmark 0.3.3__tar.gz → 0.4.0__tar.gz

{graphmark-0.3.3 → graphmark-0.4.0}/CHANGELOG.md

@@ -1,6 +1,118 @@
 # CHANGELOG
 
 
+## v0.4.0 (2026-07-25)
+
+### Features
+
+- **graph**: Add diagnose() — why a link failed, not just that it did (#111)
+  ([#114](https://github.com/cdcoonce/graphmark/pull/114),
+  [`1d124a3`](https://github.com/cdcoonce/graphmark/commit/1d124a3423fc5a6f3c8a0a084e8d15927dd1d828))
+
+Track E slice 2. graph.unresolved conflates two problems needing opposite repairs: a link matching
+  NOTHING wants its target created or deleted, a link matching TOO MUCH wants disambiguating against
+  what it collided with. A consumer holding only unresolved cannot tell them apart, so it rebuilds
+  the resolver — the drift this track exists to end.
+
+diagnose(graph, display) returns a frozen LinkDiagnosis: display echoed verbatim, target when
+  resolved, one of the six DIAGNOSIS_REASONS, and the rel_paths in play (the colliding notes for
+  ambiguous, the unindexed markdown for out-of-scope-note). The reason set is exported as a tuple in
+  decision order so a consumer can switch on it exhaustively.
+
+build() now classifies through the same function rather than agreeing with it separately — two
+  classifiers in one package would recreate the drift inside the package. Two property tests pin
+  them together: unresolved is exactly the ambiguous+missing displays, edges are exactly the
+  resolved non-self targets.
+
+candidates_for() consolidates the two-branch matching that _targets_out_of_scope_note had duplicated
+  from the resolver. It reports matches only; deciding uniqueness stays the Resolver's job, so the
+  two cannot disagree about which notes were in play. The graph now also retains the resolver it was
+  built with, so a diagnosis can never contradict its own graph.
+
+Behavior is unchanged: on the live vault, 130 unresolved / 3582 edges both before and after, and all
+  six frozen fixtures byte-identical. What is new is the answer — 8 of those 130 are ambiguous
+  collisions ([[2026-W27-tasks]] existing under both personal/archive and work/archive,
+  [[RESOURCES]] under four learning folders), which the old surface reported as plain breaks.
+
+- **graph**: Retain catalog + out_of_scope on the built graph (#110)
+  ([#113](https://github.com/cdcoonce/graphmark/pull/113),
+  [`7f7a91c`](https://github.com/cdcoonce/graphmark/commit/7f7a91cae961a06155f565384a429c92356868fb))
+
+* docs(roadmap): close Tracks C and D, open Track E (#110-#112)
+
+afk-driver --expand reads this file verbatim, so a stale one makes the fleet propose already-built
+  work and pollutes the telemetry dataset. It still targeted "v0.2.0 — every error path tested"
+  while the package is 0.3.4 with Tracks C and D both fully shipped.
+
+Track C closed (every item landed at 0.2.0). Track D marked shipped at 0.3.0, with its real
+  remaining risk named: the credibility of its flagship number. Four false-positive classes have now
+  been found by triaging a live vault against max_unresolved_links — #98 anchors (19%), #101
+  non-markdown (10%), #104 the .md extension, #107 out-of-scope notes (7%) — so "keep truthing the
+  metric before shipping a GitHub Action that fails someone's build" is the direction, not more
+  surface.
+
+Track E opened: absorb the consumer's second link stack. graphmark says whether a link resolves; the
+  gardener needs to know why it failed and what to do about it, which is why it still carries its
+  own resolver and why #107 had to be fixed in two places. Sliced #110/#111/#112, with #112 flagged
+  not-autonomous-safe past freezing the baseline — its expected values are human judgment, not
+  oracle-derived.
+
+* feat(graph): retain catalog + out_of_scope on the built graph (#110)
+
+Track E slice 1. build() computed both mappings and threw both away, so a consumer that needs to say
+  anything about a link beyond "resolved / didn't" had to rebuild the entire parse/catalog/resolve
+  stack. the-vault's graph_gardener.py does exactly that, and the two stacks drift: #107 was the
+  fourth resolution fix that had to be applied in two places.
+
+graph.catalog is normalized stem → in-scope rel_paths; a key with two or more paths IS an ambiguity
+  set, which is what lets a consumer say WHICH notes a bare link collided with instead of only that
+  it failed. graph.out_of_scope is the same for markdown outside the configured scope, retained from
+  #107. Both are constructor-optional, so three-positional construction keeps working.
+
+Value lists are sorted by rel_path explicitly rather than inheriting the walk's order. Those
+  disagree: sorted(rglob) orders Path objects by parts tuple, yielding a/note.md before a-b/note.md,
+  while rel_path string order is the reverse ('-' < '/'). The first version of the ordering tests
+  used paths where the two agree, so deleting the sorts left the suite green — caught by mutation,
+  and the tests now use the discriminating case.
+
+No behavior change: nothing about what resolves or what an edge is moves, and every frozen fixture
+  is byte-identical.
+
+
+## v0.3.4 (2026-07-25)
+
+### Bug Fixes
+
+- **graph**: Links to existing out-of-scope notes are not broken (#107)
+  ([#108](https://github.com/cdcoonce/graphmark/pull/108),
+  [`9e386f6`](https://github.com/cdcoonce/graphmark/commit/9e386f6df700b1d866b7d50854b0cc8734a08bf5))
+
+build() dropped unscoped folders, excluded dirs and rules files from the catalog and then forgot
+  they existed, so a link to one failed the resolver and landed in unresolved. The link is correct —
+  Obsidian follows it — it just points somewhere graphmark deliberately does not index, so there was
+  nothing for anyone to fix. On the live vault that was 11 of 155 reported breaks: 8 [[CLAUDE]], 1
+  [[AGENTS]], 2 into templates/.
+
+The same rglob that builds the catalog now records what it skipped, so no extra I/O buys the ability
+  to tell "exists but out of scope" apart from "exists nowhere". Consulted only AFTER the resolver
+  fails — mirroring _targets_non_note_file — so an in-graph note always wins over an out-of-scope
+  namesake and keeps its edge. Any candidate suppresses: out-of-scope notes are never link targets,
+  so ambiguity among them says nothing about whether the in-graph link is broken.
+
+Alias/anchor/.md stripping moved into a shared _strip_display so the resolver and the new check
+  cannot drift on what a display names. That refactor also strips surrounding whitespace, which the
+  resolver did not: 13 column-aligned links of the form [[folder/note | alias]] were reported broken
+  while pointing at real notes, and now resolve into edges (3570 → 3583 on the live vault). Covered
+  by its own test class.
+
+Fixtures are untouched: only the unresolved path changes shape, no expected.json carries an
+  unresolved key, and edges only grow via the whitespace fix. uv.lock catches up to the 0.3.3
+  release bump.
+
+Live vault: 155 → 130 unresolved (12 suppressed, 13 resolved), no genuine break lost — verified by
+  diffing the full before/after sets.
+
+
 ## v0.3.3 (2026-07-25)
 
 ### Bug Fixes

{graphmark-0.3.3 → graphmark-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.3.3
+Version: 0.4.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
@@ -183,8 +183,46 @@ graphmark.siloed_notes(graph)                 # reachable only through a single
 graphmark.neighborhood(graph, "a/b.md", depth=2)
 graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
+graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
+graph.out_of_scope                            # same, for markdown outside the configured scope
 ```
 
+`catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
+explain a link rather than just resolve it — which notes a bare `[[link]]` collided with, or whether
+a link that failed to resolve points at a real file you deliberately excluded. Value lists are
+sorted by rel_path.
+
+## `diagnose` — why a link failed, not just that it did
+
+`graph.unresolved` conflates two different problems. A link that matched _nothing_ needs its target
+created or deleted; a link that matched _too much_ needs disambiguating against the notes it
+collided with. `diagnose` separates them, and names the three cases that are not broken at all.
+
+```python
+d = graphmark.diagnose(graph, "2026-W27-tasks|W27 tasks")
+
+d.reason      # 'ambiguous'
+d.candidates  # ('personal/archive/tasks/2026-W27-tasks.md', 'work/archive/2026/tasks/2026-W27-tasks.md')
+d.target      # None — set only when reason == 'resolved'
+d.display     # echoed verbatim: what a human has to go and fix
+```
+
+| `reason`            | meaning                                                        | `candidates`        |
+| ------------------- | -------------------------------------------------------------- | ------------------- |
+| `resolved`          | names exactly one note; `target` is its rel_path               | —                   |
+| `ambiguous`         | names several notes, so the resolver refused to pick           | the colliding notes |
+| `non-note-file`     | targets a `.canvas` / `.base` / image / PDF — not indexed here | —                   |
+| `out-of-scope-note` | targets real markdown outside the configured scope             | the unindexed paths |
+| `missing`           | names nothing that exists — a genuine broken link              | —                   |
+| `intra-note`        | `[[#Heading]]` / `[[#^block]]` — a same-note reference         | —                   |
+
+`DIAGNOSIS_REASONS` holds that set in decision order, so a consumer can switch on it exhaustively.
+Alias, anchor and `.md` forms all diagnose identically to the bare form.
+
+`VaultGraph.build` classifies its own links through this same function, so a diagnosis can never
+contradict the graph it describes: `unresolved` is exactly the displays diagnosing as `ambiguous` or
+`missing`, and the edges are exactly the `resolved` non-self targets.
+
 ## Configuration
 
 ```toml

{graphmark-0.3.3 → graphmark-0.4.0}/README.md

@@ -156,8 +156,46 @@ graphmark.siloed_notes(graph)                 # reachable only through a single
 graphmark.neighborhood(graph, "a/b.md", depth=2)
 graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
+graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
+graph.out_of_scope                            # same, for markdown outside the configured scope
 ```
 
+`catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
+explain a link rather than just resolve it — which notes a bare `[[link]]` collided with, or whether
+a link that failed to resolve points at a real file you deliberately excluded. Value lists are
+sorted by rel_path.
+
+## `diagnose` — why a link failed, not just that it did
+
+`graph.unresolved` conflates two different problems. A link that matched _nothing_ needs its target
+created or deleted; a link that matched _too much_ needs disambiguating against the notes it
+collided with. `diagnose` separates them, and names the three cases that are not broken at all.
+
+```python
+d = graphmark.diagnose(graph, "2026-W27-tasks|W27 tasks")
+
+d.reason      # 'ambiguous'
+d.candidates  # ('personal/archive/tasks/2026-W27-tasks.md', 'work/archive/2026/tasks/2026-W27-tasks.md')
+d.target      # None — set only when reason == 'resolved'
+d.display     # echoed verbatim: what a human has to go and fix
+```
+
+| `reason`            | meaning                                                        | `candidates`        |
+| ------------------- | -------------------------------------------------------------- | ------------------- |
+| `resolved`          | names exactly one note; `target` is its rel_path               | —                   |
+| `ambiguous`         | names several notes, so the resolver refused to pick           | the colliding notes |
+| `non-note-file`     | targets a `.canvas` / `.base` / image / PDF — not indexed here | —                   |
+| `out-of-scope-note` | targets real markdown outside the configured scope             | the unindexed paths |
+| `missing`           | names nothing that exists — a genuine broken link              | —                   |
+| `intra-note`        | `[[#Heading]]` / `[[#^block]]` — a same-note reference         | —                   |
+
+`DIAGNOSIS_REASONS` holds that set in decision order, so a consumer can switch on it exhaustively.
+Alias, anchor and `.md` forms all diagnose identically to the bare form.
+
+`VaultGraph.build` classifies its own links through this same function, so a diagnosis can never
+contradict the graph it describes: `unresolved` is exactly the displays diagnosing as `ambiguous` or
+`missing`, and the edges are exactly the `resolved` non-self targets.
+
 ## Configuration
 
 ```toml

{graphmark-0.3.3 → graphmark-0.4.0}/docs/ROADMAP.md

@@ -22,11 +22,13 @@ story** — the priority consumer is the owner's vault seam (`graph_cli.py`), no
 
 ## What's shipped (baseline — do not re-propose)
 
-- **The full engine, v0.1.1 on PyPI**: `parse.py` (wikilink extraction, code-span skipping),
-  `graph.py` (catalog + `NormalizeResolver` + `VaultGraph.build`), `metrics.py` (stats, orphans,
-  hubs, clusters, bridges, siloed_notes, neighborhood, pure-python pagerank, gaps),
-  `export.py` (JSON/DOT), `cli.py`, `config.py` (`VaultConfig` + `load_config`), and
-  `dismiss.py` (content-hash weaklink dismissal store).
+- **The full engine, v0.3.4 on PyPI**: `parse.py` (wikilink extraction, code-span skipping),
+  `graph.py` (catalog + `NormalizeResolver` + `VaultGraph.build` + `unresolved`), `metrics.py`
+  (stats, orphans, hubs, clusters, bridges, siloed_notes, neighborhood, pure-python pagerank,
+  gaps), `check.py` (policy evaluation), `export.py` (JSON/DOT), `cli.py`, `config.py`
+  (`VaultConfig` + `CheckPolicy` + `load_config`), and `dismiss.py` (content-hash weaklink
+  dismissal store). Tracks A, C and D are all closed — read their sections before proposing
+  anything in those areas.
 - **Six frozen differential fixtures** — simple, alt, scoped, selflink, gaps (+ out-of-graph),
   dismiss — plus live-vault parity diffs against the reference engine.
 - **`gaps()` with injected similarity** — graphmark owns the deterministic ranking/filtering
@@ -41,38 +43,59 @@ story** — the priority consumer is the owner's vault seam (`graph_cli.py`), no
 
 ### Track A — Engine parity (CLOSED at v0.1.1 — do not re-propose engine work)
 
-### Track C — Hardening & honest surface (gate-verifiable; autonomous-safe)
+### Track C — Hardening & honest surface (CLOSED at v0.2.0 — do not re-propose)
 
-_Where we are:_ v0.1.1 is correct on its parity paths but carries correctness debt and dead
-surface no consumer exercises.
-_Where we're going:_ **v0.2.0 — every error path tested, every public knob real.**
+Every item shipped: version single-sourcing, non-UTF8 notes, dismiss-store JSON guards,
+`load_config` errors, DOT escaping, `neighborhood` on an unknown note, the dead-surface cut
+(`model.Edge/Graph/Finding` gone — `Document` is the only model type; the no-op `wikilink_pattern`
+/ `orphan_min_chars` knobs gone; the CLI `gaps` stub exits 2), the `GAPS_DEFAULT_*` banding
+constants, and the `Similarity` Protocol. `py.typed`, the 3.11–3.13 CI matrix, `--version`, and
+unified exit-code 2 for usage errors came with it.
 
-- Version single-sourcing (pyproject / `__init__.__version__` / smoke-test drift).
-- Robustness: non-UTF8 note handling in `parse_document`; JSON-corruption guards in
-  `dismiss.load_dismissed` / `active_dismissed_sigs`; `load_config` clear error on missing keys;
-  DOT identifier escaping in `to_dot`; defined behavior for `neighborhood` on an unknown note.
-- Cut or wire dead surface: `model.Edge/Graph/Finding` (never consumed — **removed in the 0.2 API
-  cut; `Document` is the only model type**); the CLI `gaps` stub
-  (null `similar_fn` — always `[]`); the silent no-op config knobs `wikilink_pattern` and
-  `orphan_min_chars` (wire them or delete them); make the dismissal-store path injectable instead
-  of hardcoding `.claude/data/connect-dismissed.json`.
-- Move the validated gaps banding policy (threshold / max-score / k / hub-degree defaults) from the
-  consumer's argparse into the package so any consumer gets the proven band.
-- A `Similarity` Protocol in `interfaces.py` typing the injected `similar_fn`.
-
-_The principle:_ each slice is single-purpose with its asserting test **pre-frozen by the
-conductor before dispatch** — the oracle-first discipline that closed the zero-test hole.
-
-### Track D — `graphmark check`: the deterministic CI gate (feature track)
+### Track D — `graphmark check`: the deterministic CI gate (SHIPPED at v0.3.0)
 
 The one unserved niche the ecosystem offers: **headless vault-health gating**. Obsidian's official
 CLI requires the desktop app; the dormant Python incumbent has no CLI; link checkers do no graph
 metrics.
 
-- `graphmark check --config ...` — thresholds (max orphans, max unresolved links, max siloed
-  notes, ...), non-zero exit on breach, byte-stable JSON report for diffing across runs.
-- Config-driven policy block (`[check]` in the TOML) so the gate is declarative.
-- Later: a thin GitHub Action wrapper. The owner's vault dogfoods the gate first.
+Shipped: `graph.unresolved`, the `[check]` policy block (`max_orphans` /
+`max_unresolved_links` / `max_siloed`, strict on unknown keys), `graphmark check` with exit 1
+reserved for breach and a byte-stable JSON report, `graphmark.build()` + curated top-level
+re-exports, and a README rewritten around the real surface.
+
+_Where we are (0.3.4):_ the gate works and the vault dogfoods it. The remaining risk is the
+**credibility of its flagship number**. Four false-positive classes have been found and fixed by
+triaging a real vault against the metric — same-note anchors (#98, 19% of the count),
+non-markdown targets (#101, 10%), the `.md` extension (#104), and links to notes that exist but
+are out of graph scope (#107, 7%). A threshold nobody trusts is not a gate.
+
+_Where we're going:_ keep truthing the metric against live vaults, then the thin GitHub Action
+wrapper — but only once the count is trustworthy enough to fail someone's build.
+
+### Track E — One resolver: absorb the consumer's second link stack (feature track)
+
+_The problem:_ the-vault's `graph_gardener.py` (Lane A) carries its **own** parse / catalog /
+normalize / resolve stack, independent of this package's. The two drift, and drift here is
+user-visible: the gardener spent weeks proposing repairs for working links that graphmark had
+already learned were fine. #107 is the fourth fix that had to be applied in two places.
+
+The gardener's stack survives because it answers questions graphmark cannot yet answer. graphmark
+says _whether_ a link resolves; Lane A needs to know **why it failed and what to do about it** —
+the ambiguity set, the near-miss candidates behind a "did you mean", and the canonical title of
+the note a display resolves to (so `[[ethan courtman]]` can be repaired to `[[Ethan Courtman]]`).
+
+_Where we're going:_ a documented, typed **link-diagnosis** surface that makes the consumer a
+formatter over graphmark's answers instead of a second resolver. The classification is already
+implicit in `build` — resolved / ambiguous / out-of-scope note / non-note file / intra-note
+reference / missing — it is simply thrown away. Candidate suggestion is the one genuinely new
+behavior, and it is the piece a human must confirm: freeze a differential oracle from the current
+gardener's hints on a real vault before changing anything.
+
+Sliced as #110 (retain the catalogs), #111 (`LinkDiagnosis` + `diagnose()`), #112 (near-miss
+suggestions — **not autonomous-safe past freezing the baseline**; the human annotation gate is the
+point of it). The consumer-side deletion is hand-coded in the vault; the package side is afk-able.
+
+_Constraint:_ this is additive. Nothing here may change what resolves or what an edge is.
 
 ### Track B — Judgment the oracle can't cover (human-validated)
 

{graphmark-0.3.3 → graphmark-0.4.0}/pyproject.toml

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

{graphmark-0.3.3 → graphmark-0.4.0}/src/graphmark/__init__.py

@@ -26,7 +26,15 @@ from graphmark.dismiss import (
     weaklink_sig,
 )
 from graphmark.export import to_dot, to_json
-from graphmark.graph import NormalizeResolver, VaultGraph, build_catalog
+from graphmark.graph import (
+    DIAGNOSIS_REASONS,
+    LinkDiagnosis,
+    NormalizeResolver,
+    VaultGraph,
+    build_catalog,
+    candidates_for,
+    diagnose,
+)
 from graphmark.interfaces import LinkExtractor, Resolver, Similarity
 from graphmark.metrics import (
     GAPS_DEFAULT_BAND,
@@ -87,6 +95,8 @@ __all__ = [
     "CheckPolicy",
     "Document",
     "LinkExtractor",
+    "DIAGNOSIS_REASONS",
+    "LinkDiagnosis",
     "NormalizeResolver",
     "Resolver",
     "Similarity",
@@ -98,6 +108,8 @@ __all__ = [
     "bridges",
     "build",
     "build_catalog",
+    "candidates_for",
+    "diagnose",
     "clusters",
     "gaps",
     "hubs",