graphmark 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,167 @@
 # CHANGELOG
 
 
+## v0.7.0 (2026-07-25)
+
+### Documentation
+
+- Record the nine-vault corpus study ([#134](https://github.com/cdcoonce/graphmark/pull/134),
+  [`7495934`](https://github.com/cdcoonce/graphmark/commit/749593468e3d57913d89fc00942179786f5f5128))
+
+graphmark has had exactly one real vault, and a coverage run showed the problem is worse than n=1:
+  that vault now has zero broken links, so it never executes the error handling at all —
+  suggest_notes entirely, the ambiguous / missing / out-of-scope verdicts, unresolved recording, and
+  diagnose(). 54% of the package is unexercised by it. The healthier it gets, the less it validates.
+
+Nine third-party vaults, zero crashes — the first evidence for the README's 'any Obsidian-family
+  vault' claim. kepano's vault is 74% .base links, which independently justifies #101 and shows the
+  reference vault understated that class by 7x. Third-party vaults sit at 1.8-27% missing against
+  the reference vault's 0%.
+
+That range confirms #127's closure against real data rather than argument: the largest
+  false-positive class this package has had moved missing by 0.4%, which no threshold can separate
+  from ordinary variation.
+
+No new defects. Two suspicious distributions were both graphmark being right, and the second was my
+  own scoping error — I excluded English template directory names but not the Spanish 'Plantillas',
+  which is the methodological lesson worth recording for anyone repeating this.
+
+- **roadmap**: Close Track E, open Track F — auditable link accounting
+  ([#128](https://github.com/cdcoonce/graphmark/pull/128),
+  [`4ca84de`](https://github.com/cdcoonce/graphmark/commit/4ca84de110dd288cd2778ccdc48a3b558367b269))
+
+* docs(roadmap): close Track E, open Track F — auditable link accounting (#124-#127)
+
+afk-driver --expand reads this file verbatim, so it has to describe where the work actually is.
+  Track E is closed at 0.6.0 (aliases were its last piece), and the baseline line still claimed
+  0.3.4.
+
+Track F names the real problem, which is not any individual bug but how bugs get found: all seven
+  correctness defects in this package's history came from a human reading link lists on the single
+  reference vault, six of them in one day. The frozen oracle is a ratchet, not a detector — it has
+  never surfaced anything new — and the one consumer's seam actively conceals package defects,
+  having hidden a 23-link alias error for six releases.
+
+The mechanism of the hiding is that the buckets are silent: build sorts every display into one of
+  six reasons and reports one of them, and six of the seven bugs were mis-bucketing. Printing the
+  distribution would have made the alias gap obvious at a glance — zero alias-resolved beside 23
+  unresolved is visibly wrong.
+
+So the epic is to make the package's own answers auditable: every display in exactly one named
+  bucket, counted, reported, and bound by a property-tested conservation law. Sliced #124-#127, with
+  the detector (#126) as the point of the exercise and its catch rate as the evidence.
+
+Records what is deliberately deferred behind it and why: the Track D GitHub Action is an adoption
+  play this repo has already decided against, and shipping a gate that fails other people's builds
+  while our own accounting is unauditable is backwards ordering. Generality work is real but is a
+  feature list, not an epic — and Track F is what will say which parts of it matter.
+
+* docs(roadmap): truth up Track D — seven classes, and the Action waits on Track F
+
+Track D still read '0.3.4' and 'four false-positive classes', and promised the GitHub Action as the
+  next step, which now contradicts Track F's deliberate deferral. afk reads this file verbatim, so a
+  contradiction in it is a contradiction injected into the expander's prompt.
+
+### Features
+
+- **cli**: Graphmark links — surface the classification distribution (#125)
+  ([#131](https://github.com/cdcoonce/graphmark/pull/131),
+  [`3ccf11c`](https://github.com/cdcoonce/graphmark/commit/3ccf11c26028c03739cfa88e67119c230645a22e))
+
+Track F slice 2. Slice 1 made the classification countable; this makes it readable. Counts sitting
+  in a Python object are worthless to a vault owner, and that gap is not cosmetic: the six-release
+  frontmatter-alias defect was legible in this distribution the whole time — 23 links reported
+  broken beside zero resolved via alias — and nobody saw it because no surface printed it.
+
+`graphmark links` emits the block as JSON on stdout with a one-line summary on stderr, so stdout
+  stays pipeable. `check`'s report carries the same block under `links`, appended after `checks` so
+  consumers already parsing that report keep working, and provably unable to change the verdict — a
+  test pins that a passing and a breaching run produce identical `links`.
+
+The byte-stability oracle in test_check.py is updated rather than sidestepped, and now pins a
+  cross-check worth having: max_unresolved_links' actual equals counts.missing, so the gate's
+  flagship number and the distribution behind it cannot silently disagree.
+
+Filed #130 along the way: every CLI example in the README fails. --config and --root live on the
+  parent parser, so argparse only accepts them before the subcommand, while the README documents the
+  opposite in all ten examples. It survived because the suite exclusively uses the working form, so
+  nothing exercised the documented one — the same shape as the rest of Track F, and the reason
+  #130's acceptance criteria require every README example to be executed by a test.
+
+Mutation testing caught that the report's zero-fill was untested: build() seeds all six keys, so
+  only a directly constructed graph exercises it. Covered now.
+
+- **graph**: Per-reason link counts and the conservation law (#124)
+  ([#129](https://github.com/cdcoonce/graphmark/pull/129),
+  [`4ba2ab6`](https://github.com/cdcoonce/graphmark/commit/4ba2ab65b32654af98f3987f2688c18af23c7f02))
+
+Track F slice 1. build sorted every extracted display into one of the six DIAGNOSIS_REASONS and then
+  kept exactly one bucket plus the edges. The other outcomes were decided and discarded, and that
+  silence is why six of the seven correctness bugs in this package's history went unnoticed: each
+  was a mis-bucketing, and nothing in the output made an implausible distribution visible.
+
+graph.link_counts accounts for every display, one bucket each, with all six keys always present in
+  DIAGNOSIS_REASONS order — a zero is a finding, so it must be reported rather than absent.
+  graph.alias_resolved counts resolutions reached through an alias, which is not a DIAGNOSIS_REASONS
+  value but is the distinction that would have made #119 visible.
+
+LinkDiagnosis gains `via` ("stem" or "alias") so the counter reads the classifier's own verdict
+  instead of re-deriving it. Re-deriving is how the two would eventually disagree, which is the
+  failure this repo has spent Track E removing.
+
+The conservation law — sum(link_counts.values()) equals the extractor's total — is asserted on a
+  vault exercising all six outcomes, on the frozen fixtures, and against the pre-existing surface
+  (unresolved occurrences == ambiguous + missing), so the new tally cannot drift from the old one.
+
+On the live 521-note vault the payoff is legible in one line. Healthy: missing 0, alias-resolved 23.
+  The same vault with aliases disabled, which is what the six-release defect actually looked like:
+  missing 23, alias-resolved 0. Same 6226 total either way — nothing vanished, 23 links were in the
+  wrong bucket, and now you can see that.
+
+Purely additive: no metric changes, frozen fixtures byte-identical.
+
+### Testing
+
+- Property-based vault generation — Track F's detector (#126)
+  ([#132](https://github.com/cdcoonce/graphmark/pull/132),
+  [`cd76410`](https://github.com/cdcoonce/graphmark/commit/cd76410087157677f6f6515c94d11057060063eb))
+
+The frozen oracle prevents regression and has never surfaced anything new, because fixtures only
+  encode shapes somebody already thought of, and all seven historical bugs were shapes nobody
+  thought of. This generates vaults nobody designed and asserts what must hold for any content at
+  all.
+
+Two layers, and the second is the one that matters.
+
+STRUCTURAL invariants over generated vaults: conservation (every extracted display lands in a
+  bucket), edges name real notes and never exceed the resolved count, self-links never become edges,
+  back_links mirror out_links, unresolved is exactly ambiguous+missing, aliases never shadow a real
+  note name, and build is deterministic — the headline claim of this package, asserted nowhere until
+  now.
+
+Those all passed on first run, which was the finding. Every one of the seven bugs kept conservation
+  intact; each merely filed a link in the WRONG bucket. So the structural layer would have caught
+  none of them, and shipping only that would have been a detector that cannot see the thing it
+  exists for.
+
+METAMORPHIC relations close that gap. Obsidian treats [[X]], [[X|alias]], [[X#Section]] and [[X.md]]
+  as the same link, so each rewrite must leave the counts and edges identical. Re-injecting the real
+  defects confirms the layer works: #104 (.md), #98 (intra-note), #101 (non-note file), #119
+  (aliases) and the path-qualified whitespace bug each fail a property.
+
+Two of those properties were over-specified on first write — they compared `unresolved`, which
+  echoes the RAW display, so a rewrite legitimately changes it. Comparing it asserts a rewrite does
+  not rewrite anything. They now compare counts and edges, with the reason documented at the helper.
+
+The whitespace property also had to be sharpened: normalization collapses whitespace on its own, so
+  a padded BARE display resolves either way and cannot detect the defect. Only the path-suffix
+  branch is sensitive, which is exactly where the 13 live links were reported broken while pointing
+  at real notes.
+
+hypothesis is a dev dependency only; the shipped runtime dep is still networkx alone. Bounded and
+  derandomized so CI stays fast and failures reproduce.
+
+
 ## v0.6.0 (2026-07-25)
 
 ### Bug Fixes

{graphmark-0.6.0 → graphmark-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.6.0
+Version: 0.7.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
@@ -21,6 +21,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: networkx>=3.0
 Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -84,12 +85,32 @@ graphmark siloed                         --root /path/to/vault
 graphmark neighborhood --note a/b.md --depth 2  --root /path/to/vault
 graphmark pagerank --n 10 --alpha 0.85   --root /path/to/vault
 graphmark export dot                     --root /path/to/vault > graph.dot
+graphmark links                          --root /path/to/vault
 graphmark check                          --config vault.toml
 ```
 
 Exit codes: `0` success, `1` a `check` threshold breach, `2` a usage or config error. Nothing else
 uses `1`, so CI can trust it.
 
+## `graphmark links` — how every link was classified
+
+```console
+$ graphmark --root /path/to/vault links
+{"total": 6226, "counts": {"resolved": 6169, "ambiguous": 0, "non-note-file": 17, "out-of-scope-note": 0, "missing": 0, "intra-note": 40}, "alias_resolved": 23}
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+JSON on stdout, the one-line summary on stderr, so the output stays pipeable.
+
+Every wikilink lands in exactly one bucket and the buckets sum to `total` — nothing is silently
+dropped. All six reasons are always present, because a zero is a finding: the line above with
+`missing 23 · alias-resolved 0` instead is what a real defect looked like before frontmatter aliases
+resolved, on the same vault with the same 6226 total. Reading the distribution is the fastest way to
+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.
+
 ## `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
@@ -186,7 +207,26 @@ 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
 graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
+graph.link_counts                             # {reason: occurrences} — every link, one bucket each
+graph.alias_resolved                          # how many resolutions came via an alias
+```
+
+`link_counts` accounts for **every** display the extractor produced, one bucket each, and always
+carries all six `DIAGNOSIS_REASONS` — a zero is a finding, not a non-event. The buckets sum to the
+extraction count, so nothing is silently dropped. Reading the distribution is the fastest way to
+notice the tool is wrong about your vault:
+
+```
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+versus the same vault with alias resolution disabled — the shape of a real defect that once shipped:
+
 ```
+resolved 6146 · ... · missing 23 · ... · alias-resolved 0
+```
+
+Same total, 23 links in the wrong bucket.
 
 `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

{graphmark-0.6.0 → graphmark-0.7.0}/README.md

@@ -57,12 +57,32 @@ graphmark siloed                         --root /path/to/vault
 graphmark neighborhood --note a/b.md --depth 2  --root /path/to/vault
 graphmark pagerank --n 10 --alpha 0.85   --root /path/to/vault
 graphmark export dot                     --root /path/to/vault > graph.dot
+graphmark links                          --root /path/to/vault
 graphmark check                          --config vault.toml
 ```
 
 Exit codes: `0` success, `1` a `check` threshold breach, `2` a usage or config error. Nothing else
 uses `1`, so CI can trust it.
 
+## `graphmark links` — how every link was classified
+
+```console
+$ graphmark --root /path/to/vault links
+{"total": 6226, "counts": {"resolved": 6169, "ambiguous": 0, "non-note-file": 17, "out-of-scope-note": 0, "missing": 0, "intra-note": 40}, "alias_resolved": 23}
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+JSON on stdout, the one-line summary on stderr, so the output stays pipeable.
+
+Every wikilink lands in exactly one bucket and the buckets sum to `total` — nothing is silently
+dropped. All six reasons are always present, because a zero is a finding: the line above with
+`missing 23 · alias-resolved 0` instead is what a real defect looked like before frontmatter aliases
+resolved, on the same vault with the same 6226 total. Reading the distribution is the fastest way to
+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.
+
 ## `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
@@ -159,7 +179,26 @@ 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
 graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
+graph.link_counts                             # {reason: occurrences} — every link, one bucket each
+graph.alias_resolved                          # how many resolutions came via an alias
+```
+
+`link_counts` accounts for **every** display the extractor produced, one bucket each, and always
+carries all six `DIAGNOSIS_REASONS` — a zero is a finding, not a non-event. The buckets sum to the
+extraction count, so nothing is silently dropped. Reading the distribution is the fastest way to
+notice the tool is wrong about your vault:
+
+```
+resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23
+```
+
+versus the same vault with alias resolution disabled — the shape of a real defect that once shipped:
+
 ```
+resolved 6146 · ... · missing 23 · ... · alias-resolved 0
+```
+
+Same total, 23 links in the wrong bucket.
 
 `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

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

@@ -22,13 +22,14 @@ 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.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.
+- **The full engine, v0.6.0 on PyPI**: `parse.py` (wikilink extraction, code-span skipping,
+  frontmatter incl. block lists), `graph.py` (catalog + `NormalizeResolver` + `VaultGraph.build` +
+  `unresolved` + `diagnose`/`LinkDiagnosis` + frontmatter aliases), `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, D and E 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
@@ -63,14 +64,17 @@ Shipped: `graph.unresolved`, the `[check]` policy block (`max_orphans` /
 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 are (0.6.0):_ the gate works and the vault dogfoods it. The remaining risk is the
+**credibility of its flagship number**. Seven false-positive classes have been found and fixed —
+same-note anchors (#98, 19% of the count), non-markdown targets (#101, 10%), whitespace-padded
+displays, the `.md` extension (#104), out-of-scope notes (#107, 7%), frontmatter aliases (#119,
+**23 phantom breaks against an actual 0**), and Unicode NFD/NFC (#123). 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.
+_Where we're going:_ **Track F, not the GitHub Action.** Every one of those seven was found by a
+human reading link lists on one vault, which does not scale and has no reason to be finished. The
+Action ships once the accounting underneath it is auditable — see Track F for why that ordering is
+deliberate.
 
 ### Track E — One resolver: absorb the consumer's second link stack (feature track)
 
@@ -97,6 +101,55 @@ point of it). The consumer-side deletion is hand-coded in the vault; the package
 
 _Constraint:_ this is additive. Nothing here may change what resolves or what an edge is.
 
+**CLOSED at v0.6.0.** #110/#111/#112 shipped, and frontmatter aliases moved in-package (#119) —
+the last piece of the consumer's parallel stack. the-workshop#474 deletes the consumer side.
+
+### Track F — Auditable link accounting (the current epic)
+
+_The problem is not any individual bug; it is how they get found._ Every correctness bug in this
+package's history was found the same way: a human reading link lists from **one** vault. Seven so
+far — #98 same-note anchors, #101 non-markdown targets, #104 the `.md` extension, #107 out-of-scope
+notes, #119 frontmatter aliases, #123 Unicode NFD/NFC, plus the whitespace-padded displays fixed
+alongside #107. Six of those seven landed in a single day of hand-triage.
+
+The frozen differential oracle is a **ratchet, not a detector.** It prevents regression superbly and
+has never once surfaced something new. Worse, the single consumer's seam actively _conceals_
+package defects: its `AliasResolver` hid a 23-link error for six releases, because the only vault
+that could have exposed the gap had already patched around it.
+
+_Why the bugs hide:_ the buckets are silent. `build` sorts every extracted display into one of the
+six `DIAGNOSIS_REASONS`, then reports **one** of them. A vault owner sees `N unresolved` and nothing
+about what was suppressed — and six of the seven bugs were _mis-bucketing_, a link filed as
+`unresolved` that belonged in `resolved` or the reverse. Had graphmark printed
+
+```
+3677 edges · 23 unresolved · 0 alias-resolved · 12 out-of-scope · 8 non-note-file · 19 intra-note
+```
+
+the alias gap would have been obvious at a glance: zero alias-resolved beside 23 unresolved is
+visibly wrong. Nobody could see it, so nobody saw it for six releases.
+
+_Where we're going:_ **every extracted display lands in exactly one named bucket; the buckets are
+counted, reported, and bound by a property-tested conservation law.** The aim is not another metric
+— it is to make the package's own answers auditable, so an implausible distribution is visible to
+its owner without a day of triage. That is the mechanism that scales past one vault and one human,
+and it is the strongest possible expression of the "public correctness story" identity.
+
+Sliced as #124 (per-reason counts + the conservation law), #125 (`graphmark links` surfaces the
+distribution), #126 (property-based vault generation — **the detector**; expect it to fail on first
+run, and file what it finds), #127 (implausibility heuristics — advisory only, **not
+autonomous-safe past the exact checks**, since the statistical thresholds need the same human
+calibration gate #112 used).
+
+Track F's own success measure is not slices merged: it is **bugs found by machinery rather than by
+a human reading link lists.** #126's catch rate is the evidence.
+
+_Deliberately deferred behind this:_ the Track D GitHub Action. It is an adoption play, and adoption
+is not this repo's game; more to the point, shipping a gate that fails other people's builds while
+the tool's own accounting is unauditable is backwards ordering. Generality work (Windows paths,
+markdown-style `[text](note.md)` links for wikilink-disabled vaults, non-my-brain schemas) is real
+but is a feature list, not an epic — and this track is what will tell us which parts of it matter.
+
 ### Track B — Judgment the oracle can't cover (human-validated)
 
 - New fixtures on a **different schema** than my-brain have hand-authored expected values → a human

{graphmark-0.6.0 → graphmark-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphmark"
-version = "0.6.0"
+version = "0.7.0"
 description = "Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -27,7 +27,7 @@ Repository = "https://github.com/cdcoonce/graphmark"
 Issues = "https://github.com/cdcoonce/graphmark/issues"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0", "ruff>=0.6"]
+dev = ["pytest>=8.0", "ruff>=0.6", "hypothesis>=6.100"]
 
 [project.scripts]
 graphmark = "graphmark.cli:main"

{graphmark-0.6.0 → graphmark-0.7.0}/src/graphmark/__init__.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
 
-from graphmark.check import run_check, unresolved_link_count
+from graphmark.check import links_report, run_check, unresolved_link_count
 from graphmark.config import CheckPolicy, VaultConfig, load_config
 from graphmark.dismiss import (
     active_dismissed_sigs,
@@ -128,6 +128,7 @@ __all__ = [
     "pagerank",
     "parse_document",
     "record_dismissal",
+    "links_report",
     "run_check",
     "siloed_notes",
     "stats",

{graphmark-0.6.0 → graphmark-0.7.0}/src/graphmark/check.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from dataclasses import fields
 
 from graphmark.config import VaultConfig
-from graphmark.graph import VaultGraph
+from graphmark.graph import DIAGNOSIS_REASONS, VaultGraph
 from graphmark.metrics import orphans, siloed_notes
 
 
@@ -20,6 +20,32 @@ def unresolved_link_count(graph: VaultGraph) -> int:
     return sum(len(displays) for displays in graph.unresolved.values())
 
 
+def links_report(graph: VaultGraph) -> dict:
+    """How every wikilink in the vault was classified, as a byte-stable block.
+
+    The counts exist on the graph after a build, but a vault owner cannot read a Python object.
+    That gap is not cosmetic: the six-release frontmatter-alias defect was legible in this
+    distribution the entire time — many links reported broken beside zero resolved via alias — and
+    nobody saw it because no surface printed it.
+
+    Key order is fixed here and reasons follow ``DIAGNOSIS_REASONS``, so two runs over an unchanged
+    vault diff to nothing, matching ``run_check``'s existing contract.
+    """
+    counts = {reason: graph.link_counts.get(reason, 0) for reason in DIAGNOSIS_REASONS}
+    return {
+        "total": sum(counts.values()),
+        "counts": counts,
+        "alias_resolved": graph.alias_resolved,
+    }
+
+
+def links_summary_line(report: dict) -> str:
+    """One human-readable line of the distribution, for stderr."""
+    parts = [f"{reason} {count}" for reason, count in report["counts"].items()]
+    parts.append(f"alias-resolved {report['alias_resolved']}")
+    return " · ".join(parts)
+
+
 def _actual(name: str, graph: VaultGraph, config: VaultConfig) -> int:
     if name == "max_orphans":
         # Honors transient_prefixes, so scratch/daily notes do not fail the gate.
@@ -53,7 +79,13 @@ def run_check(graph: VaultGraph, config: VaultConfig) -> dict:
         # "max" is inclusive: exactly at the limit passes.
         checks.append({"name": f.name, "limit": limit, "actual": actual, "pass": actual <= limit})
 
-    return {"pass": all(c["pass"] for c in checks), "checks": checks}
+    # `links` is appended, never interleaved, so consumers already parsing this report keep
+    # working. It is context for reading the verdict and can never change it.
+    return {
+        "pass": all(c["pass"] for c in checks),
+        "checks": checks,
+        "links": links_report(graph),
+    }
 
 
 def breach_lines(report: dict) -> list[str]:

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

@@ -10,7 +10,7 @@ from pathlib import Path
 import networkx as nx
 
 from graphmark import __version__, build
-from graphmark.check import breach_lines, run_check
+from graphmark.check import breach_lines, links_report, links_summary_line, run_check
 from graphmark.config import VaultConfig, load_config
 from graphmark.export import to_dot, to_json
 from graphmark.graph import VaultGraph
@@ -83,6 +83,11 @@ def main() -> None:
 
     sub.add_parser("gaps", help="Link-gap suggestions (library-only; see the README)")
 
+    sub.add_parser(
+        "links",
+        help="How every wikilink was classified: counts per reason, plus alias resolutions",
+    )
+
     sub.add_parser(
         "check",
         help="Gate vault health against the config's [check] thresholds (exit 1 on breach)",
@@ -140,6 +145,11 @@ def main() -> None:
         print(to_json(result))
     elif args.command == "export" and args.format == "dot":
         print(to_dot(graph))
+    elif args.command == "links":
+        report = links_report(graph)
+        print(to_json(report))
+        # stdout stays pipeable JSON; the at-a-glance line goes to stderr, as breach_lines does.
+        print(links_summary_line(report), file=sys.stderr)
     elif args.command == "check":
         try:
             report = run_check(graph, config)

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

@@ -293,12 +293,20 @@ class LinkDiagnosis:
     ``candidates`` carries the rel_paths in play: the colliding notes for ``ambiguous``, the
     unindexed markdown for ``out-of-scope-note``, and — only when ``diagnose`` is asked for them —
     the near-miss suggestions for ``missing``. Empty for every other reason.
+
+    ``via`` distinguishes the two ways a link can resolve. That distinction is not cosmetic: an
+    alias resolution looked identical to a stem resolution, and a vault reporting many broken links
+    beside zero alias resolutions is the exact signature of the defect that hid for six releases.
     """
 
     display: str
     target: str | None = None
     reason: str = "missing"
     candidates: tuple[str, ...] = field(default=())
+    #: How a ``resolved`` verdict was reached — ``"stem"`` (catalog name or path suffix) or
+    #: ``"alias"`` (frontmatter ``aliases:``). ``None`` for every other reason. Recorded here
+    #: rather than re-derived by callers, so a counter can never disagree with the classifier.
+    via: str | None = None
 
 
 def _diagnose(
@@ -320,7 +328,7 @@ def _diagnose(
 
     target = resolver.resolve(display, catalog)
     if target is not None:
-        return LinkDiagnosis(display=display, target=target, reason="resolved")
+        return LinkDiagnosis(display=display, target=target, reason="resolved", via="stem")
 
     # The resolver runs first, so a real note named X always beats an alias X — otherwise renaming
     # a note could silently hijack live links. An alias hit is a genuine resolution, not a
@@ -336,7 +344,9 @@ def _diagnose(
         if stripped and "/" not in stripped:
             aliased = aliases.get(_normalize(stripped))
             if aliased is not None:
-                return LinkDiagnosis(display=display, target=aliased, reason="resolved")
+                return LinkDiagnosis(
+                    display=display, target=aliased, reason="resolved", via="alias"
+                )
 
     # The resolver declined. Whether it declined because nothing matched or because too much did
     # is the distinction consumers need, and only the catalog can answer it.
@@ -403,6 +413,8 @@ class VaultGraph:
         out_of_scope: dict[str, list[str]] | None = None,
         resolver: Resolver | None = None,
         aliases: dict[str, str] | None = None,
+        link_counts: dict[str, int] | None = None,
+        alias_resolved: int = 0,
     ) -> None:
         self.nodes = nodes
         self.out_links = out_links
@@ -411,6 +423,8 @@ class VaultGraph:
         self.catalog = catalog if catalog is not None else {}
         self.out_of_scope = out_of_scope if out_of_scope is not None else {}
         self.aliases = aliases if aliases is not None else {}
+        self.link_counts = link_counts if link_counts is not None else {}
+        self.alias_resolved = alias_resolved
         # Retained so diagnose() answers with the same resolver that built the graph; a
         # pluggable Resolver that disagreed with the graph it describes would be worse than none.
         self.resolver: Resolver = resolver if resolver is not None else NormalizeResolver()
@@ -466,9 +480,16 @@ class VaultGraph:
         # the raw display is recorded once per occurrence, since that is what a human goes and
         # fixes.
         broken = {"ambiguous", "missing"}
+        # Every extracted display lands in exactly one bucket. All six keys are seeded so a zero
+        # 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
         for doc in docs:
             for display in extractor.extract(doc.text):
                 d = _diagnose(display, catalog, out_of_scope, resolver, aliases)
+                link_counts[d.reason] += 1
+                if d.via == "alias":
+                    alias_resolved += 1
                 if d.reason in broken:
                     unresolved.setdefault(doc.rel_path, []).append(display)
                 elif d.target is not None and d.target != doc.rel_path:
@@ -479,5 +500,14 @@ class VaultGraph:
                 back_links[dst].add(src)
 
         return cls(
-            nodes, out_links, back_links, unresolved, catalog, out_of_scope, resolver, aliases
+            nodes,
+            out_links,
+            back_links,
+            unresolved,
+            catalog,
+            out_of_scope,
+            resolver,
+            aliases,
+            link_counts,
+            alias_resolved,
         )

{graphmark-0.6.0 → graphmark-0.7.0}/tests/test_check.py

@@ -108,11 +108,17 @@ class TestThresholdSemantics:
 class TestByteStability:
     """The report must diff cleanly across runs — pinned against a literal."""
 
+    # The `links` block is appended after `checks`, so existing consumers keep parsing what they
+    # already parsed. Note the cross-check the literal now pins: max_unresolved_links' actual (1)
+    # equals counts.missing (1) — the gate's flagship number and the distribution behind it cannot
+    # silently disagree.
     EXPECTED = (
         '{"pass": false, "checks": ['
         '{"name": "max_orphans", "limit": 1, "actual": 2, "pass": false}, '
         '{"name": "max_unresolved_links", "limit": 0, "actual": 1, "pass": false}, '
-        '{"name": "max_siloed", "limit": 0, "actual": 0, "pass": true}]}'
+        '{"name": "max_siloed", "limit": 0, "actual": 0, "pass": true}], '
+        '"links": {"total": 7, "counts": {"resolved": 6, "ambiguous": 0, "non-note-file": 0, '
+        '"out-of-scope-note": 0, "missing": 1, "intra-note": 0}, "alias_resolved": 0}}'
     )
 
     def test_cli_report_is_byte_identical_to_the_oracle(self, tmp_path, capsys):