Merge pull request #34 from HarperZ9/feat/repo-art-and-diagrams

Draw the claim oracle, and give index its own generated header

Author: HarperZ9

.gitattributes

@@ -0,0 +1 @@
+docs/art/*.svg text eol=lf

README.md

@@ -1,4 +1,4 @@
-<p align="center"><img src=".github/assets/zentropy-banner.png" alt="index: Maps a multi-repo workspace in seconds on the nine-ecosystem reference tree it ships with (self-measured): nine ecosystems, dependency and symbol graphs, fully offline, zero dependencies." width="100%"></p>
+<p align="center"><img src="docs/art/index-header.svg" alt="index: map a workspace offline, and refute a claim the code does not support." width="100%"></p>
 
 **Maps a multi-repo workspace in seconds on the nine-ecosystem reference tree it ships with (self-measured): nine ecosystems, dependency and symbol graphs, fully offline, zero dependencies.**
 
@@ -43,6 +43,22 @@ New here? [`docs/INTRODUCTION.md`](docs/INTRODUCTION.md) is the ten-minute walkt
 
 Every codebase has a shape. Past a handful of repos, that shape lives only in someone's head, and they are usually busy or already gone. `index` draws it for you: how your repositories depend on each other, what lives inside each one down to the symbol level, and the docs that explain why, as maps you can open, search, and re-derive. It reads nine ecosystems (Python, JavaScript and TypeScript, Rust, Go, Java, C#, Ruby, PHP, C and C++) from their manifests and their real imports, and it records each dependency edge with the file and line that shows it. Pure Python 3.11+ standard library, zero runtime dependencies.
 
+## How a claim is settled
+
+`index verify` answers a structural claim from the graph it extracted, not from
+a model's memory. This is the path one claim takes.
+
+<p align="center"><img src="docs/art/claim-oracle.svg" alt="Eight stages from workspace discovery to a rechecked certificate: discover, classify, graph, freshness, claim, ground, certificate, recheck. Fingerprints ask whether ground truth has moved, and a graph built over changed code is rebuilt before any claim is grounded against it. A claim is answered from the graph rather than from memory, ending as match, refuted or unverifiable." width="100%"></p>
+
+The triad here is deliberately not the one `index wiki --verify` reports. A
+sealed artifact can DRIFT away from a tree that moved underneath it. A claim
+cannot drift: either the graph carries the edge, or the graph is complete on
+that point and does not, which is REFUTED. UNVERIFIABLE is reserved for the case
+where the question itself falls outside what was scanned, such as an endpoint
+that is not a repository in the workspace. A MATCH on a dependency hands back
+the file and line of its strongest supporting edge, so the answer arrives with
+its witness rather than as an assertion you have to take on faith.
+
 ## The surfaces, coolest first
 
 **`index wiki`, the single-repo wiki.** Model-based wiki generators write confident prose about structure that is not there; repo packers dump source without comprehending it. `index wiki` takes the third path: it derives the wiki for one repo from the module and symbol graph it extracts itself, and generates no prose at all. You get an overview page, one page per module with imports, dependents, and cycle membership, one page per Python function, class, and method with its callers and callees, and an architecture diagram rendered from the real dependency graph. Point it at a git URL (`index wiki https://github.com/org/repo`) and it shallow-clones, derives, and cleans up, so you can read a repo you have not checked out. The artifact is commit-pinned and sealed, and `index wiki --verify` re-checks it against the current tree: MATCH, DRIFT, or UNVERIFIABLE, exit codes 0, 1, 2.

docs/art/claim-oracle.svg

@@ -0,0 +1,36 @@
+{
+  "$comment": "Source of truth for the artwork on this repository's front page. Edit a sentence here and re-run scripts/render_repo_art.py; tests/test_repo_art.py fails if the committed SVG stops matching.",
+  "header": {
+    "name": "index",
+    "role": "offline workspace graph",
+    "tagline": "Map a workspace offline. Refute a claim the code does not support.",
+    "words": ["scan", "graph", "symbols", "verify", "certificate"]
+  },
+  "flows": [
+    {
+      "file": "claim-oracle.svg",
+      "kicker": "one claim, end to end",
+      "title": "How a structural claim is settled against the code itself",
+      "alt": "Eight stages from workspace discovery to a rechecked certificate. Fingerprints ask whether ground truth has moved, and a graph built over changed code is rebuilt before any claim is grounded against it. A claim is answered from the graph rather than from memory, ending as match, refuted or unverifiable.",
+      "footnote": "The verdict is computed from the graph, so an agent's confidence has no route into it.",
+      "stages": [
+        {"title": "Discover", "note": "The workspace is walked and pruned into a repo list."},
+        {"title": "Classify", "note": "Each repo takes its ecosystem from its own manifests."},
+        {"title": "Graph", "note": "Imports and symbols become edges carrying a file and line."},
+        {"title": "Freshness", "note": "Fingerprints answer one question: has ground truth moved?"},
+        {"title": "Claim", "note": "An agent asserts a dependency, or that a symbol exists."},
+        {"title": "Ground", "note": "The claim meets the graph, and never the agent's memory."},
+        {"title": "Certificate", "note": "The verdict is sealed over a hash of the whole graph."},
+        {"title": "Recheck", "note": "A consumer recomputes that hash instead of trusting it."}
+      ],
+      "returns": [
+        {"from": 3, "to": 2, "label": "GROUND TRUTH MOVED: THE GRAPH IS REBUILT FIRST"}
+      ],
+      "outcomes": [
+        {"label": "MATCH", "note": "the graph carries the edge, with file and line", "tone": "verified"},
+        {"label": "REFUTED", "note": "the graph is complete here, with no such edge", "tone": "drift"},
+        {"label": "UNVERIFIABLE", "note": "an endpoint sits outside the scanned workspace", "tone": "none"}
+      ]
+    }
+  ]
+}

docs/art/index-header.svg

@@ -0,0 +1,73 @@
+"""Render a repository's front-page artwork from its spec.
+
+    python scripts/render_repo_art.py            # write the SVGs
+    python scripts/render_repo_art.py --check    # fail if any is stale
+
+The check mode is the point. Committed artwork drifts from the words it
+illustrates the moment someone edits one and not the other, and nobody
+notices, because a picture in a README is never diffed. Here the picture is
+a pure function of a spec that IS diffable, so a test can re-render and
+compare bytes.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from repo_art import header_svg  # noqa: E402
+from repo_flow import flow_svg  # noqa: E402
+
+ART = Path(__file__).resolve().parents[1] / "docs" / "art"
+
+
+def rendered(spec_path: Path) -> dict[Path, str]:
+    """Every file one spec produces, as path to text."""
+    spec = json.loads(spec_path.read_text(encoding="utf-8"))
+    stem = spec_path.name.removesuffix(".art.json")
+    out = {spec_path.parent / f"{stem}-header.svg": header_svg(spec["header"])}
+    for flow in spec.get("flows", []):
+        out[spec_path.parent / flow["file"]] = flow_svg(flow)
+    return out
+
+
+def specs() -> list[Path]:
+    return sorted(ART.glob("*.art.json"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true",
+                        help="report stale artwork instead of rewriting it")
+    args = parser.parse_args(argv)
+
+    stale: list[str] = []
+    for spec_path in specs():
+        for path, text in rendered(spec_path).items():
+            body = text + "\n"
+            if args.check:
+                current = path.read_text(encoding="utf-8") if path.exists() else ""
+                if current != body:
+                    stale.append(str(path.relative_to(ART.parents[1])))
+                continue
+            # newline="" so a Windows run writes the same bytes a Linux
+            # run does. The whole point of this file is that committed
+            # artwork and a fresh render are comparable.
+            path.write_text(body, encoding="utf-8", newline="")
+            print(f"wrote {path.relative_to(ART.parents[1])} ({len(body)} bytes)")
+
+    if stale:
+        print("stale artwork, re-run scripts/render_repo_art.py:", file=sys.stderr)
+        for name in stale:
+            print(f"  {name}", file=sys.stderr)
+        return 1
+    if args.check:
+        print(f"artwork matches its spec ({len(specs())} spec files)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())