veridge 0.1.0__tar.gz

veridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lodestar contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

veridge-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: veridge
+Version: 0.1.0
+Summary: The always-fresh, low-token map of a whole project — docs, code (to the symbol), decisions — ranked by what matters and served to AI and humans alike.
+License: MIT
+Keywords: knowledge-graph,code-graph,ai-agents,context,mcp,pagerank,repo-map
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: treesitter
+Requires-Dist: tree-sitter>=0.21; extra == "treesitter"
+Requires-Dist: tree-sitter-language-pack>=0.2; extra == "treesitter"
+Dynamic: license-file
+
+# Veridge
+
+[![CI](https://github.com/galimar/veridge/actions/workflows/ci.yml/badge.svg)](https://github.com/galimar/veridge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-none-success.svg)](pyproject.toml)
+
+**The always-fresh, low-token map of a *whole* project** — documents, code (down to the
+function/class), decisions and work sessions — unified in one typed graph, **ranked by what
+matters**, and served both to an AI assistant (as the minimal relevant context) and to a human.
+
+> *Veridge* fuses **veridical** (truthful, verified) with **ridge** — the crest line that runs
+> through and connects a whole terrain. That's what it builds: the *true, always-fresh backbone*
+> of how a project fits together — the structural through-line you and your assistant navigate by.
+
+---
+
+## Why it exists
+
+A project's knowledge lives in three places that drift apart: the **code**, the **documents**
+(designs, decisions, notes) and the **history** of how it got here. As it grows, keeping a
+mental model of how everything connects gets harder — and an AI assistant loses the thread
+between one session and the next, so every session restarts by re-reading and re-searching
+files. That is slow, incomplete, and burns tokens repeatedly.
+
+Veridge builds the project's graph **once** and keeps it fresh, then answers questions about it
+in a few hundred tokens. It unifies documents, code (down to the symbol), decisions and sessions
+in one map, **ranks** it so an answer is the *relevant* slice rather than everything, and serves
+that slice within a token budget — to an AI assistant and to a human alike.
+
+## What makes it different
+
+| Pillar | What it means |
+|---|---|
+| **One unified graph** | files **+ symbols** (functions/classes) **+ areas + decisions + git sessions** — code, docs and history in a single map. |
+| **Symbol-level, with a real call graph** | Python is parsed with the stdlib `ast` into a `defines`/`imports`/`calls` graph. Other languages plug in via the optional `[treesitter]` extra. |
+| **Ranked by relevance** | global **PageRank** ("what matters in this project") and **personalised PageRank** ("what matters *for this task*"). |
+| **Token-budgeted, task-aware** | `veridge focus "<task>"` returns the **minimal relevant subgraph within a token budget** — relevant context, not the whole repo. |
+| **Anti-drift gate** | content-hash freshness: refuses to call the map "fine" while something is stale, broken or orphaned. |
+| **Zero infrastructure** | the core runs on the **Python standard library alone** — no DB, no embeddings, no server. Read-only on your sources. |
+| **MCP-first** | the same ranked, budgeted queries are exposed to MCP-aware assistants behind an optional extra. |
+
+It is **not a RAG system**: no embeddings, no vector store, no LLM to build the graph. It maps
+*structure* and *importance*, which makes it complementary to RAG and purpose-built for one
+thing: **the cheapest accurate context for orienting on a project.**
+
+## Install
+
+```bash
+pip install -e .                      # from a clone
+pip install -e ".[mcp]"               # + optional MCP server
+pip install -e ".[treesitter]"        # + symbol-level JS/TS/Go/Rust/Java parsing
+```
+
+Requires Python 3.10+. Runtime dependencies of the core: **none**.
+
+## Quickstart
+
+```bash
+veridge build  .                 # index -> .veridge/graph.json (+ manifest)
+veridge map    .                 # PageRank-ranked digest: areas, sizes, what matters
+veridge focus  "<task>" .        # the signature query: minimal relevant subgraph, budgeted
+veridge impact src/util.py .     # blast-radius: what a change here affects (ranked, budgeted)
+veridge impact --diff .          # blast-radius of your current working changes (vs git HEAD)
+veridge tour   .                 # dependency-ordered reading tour of the key files
+veridge why    src/cli.py src/model.py .   # shortest typed path between two nodes
+veridge find   greet .           # find nodes (files or symbols) by name/path
+veridge neighbors src/util.py .  # a node and its typed connections
+veridge gate   .                 # anti-drift: broken refs, stale files, orphans
+veridge stats  .                 # counts by node/edge type
+```
+
+`veridge map` also groups files by **architectural layer** (entrypoint / api / service / core /
+data / ui / util / tests / config / docs) — inferred heuristically, no LLM.
+
+### The signature query: `focus`
+
+Give it a task, a file, or a symbol name and a token budget. It seeds a **personalised
+PageRank** on whatever the query matches, then admits the highest-ranked nodes until the
+budget is spent — returning exactly the context worth loading, and nothing else:
+
+```text
+$ veridge focus "personalised pagerank ranking" . --budget 400
+focus 'personalised pagerank ranking' · 24 nodes · ~391/400 tokens
+  seeds: veridge/rank.py#pagerank, tests/test_rank_budget.py#test_personalised_pagerank...
+  0.1487  veridge/rank.py#pagerank             [symbol, deg 8]
+  0.0334  veridge/query.py#focus               [symbol, deg 10]
+  0.0289  veridge/query.py#project_map         [symbol, deg 9]
+  0.0243  veridge/budget.py                    [file,   deg 8]
+  ...
+```
+
+### Blast-radius: `impact`
+
+"If I change this, what breaks — and what's the minimal context to review it safely?" That's
+*reverse reachability* over the call/import/reference graph, so Veridge answers it **for free
+and exactly** — no LLM call, no token cost. The affected set is ranked by a proximity-weighted
+PageRank and trimmed to a token budget, so even a hub with hundreds of dependents returns its
+most important ones:
+
+```text
+$ veridge impact veridge/model.py . --budget 300
+impact (dependents) of 'veridge/model.py' · 82 affected by
+  showing 20 · ~290/300 tokens
+  0.0256  d2  veridge/query.py#impact     [symbol]
+  0.0239  d1  veridge/query.py            [file]
+  0.0226  d1  veridge/cli.py              [file]
+  ...
+```
+
+`d1`/`d2` is the propagation distance. Use `--diff` to seed from your working changes
+(`git diff --name-only HEAD`) — "the blast-radius of what I'm about to commit" — or `--deps` to
+invert the question (what the seed *relies on*).
+
+Same idea over MCP:
+
+```bash
+pip install -e ".[mcp]"
+veridge-mcp .      # serves project_map / focus / impact / find / neighbors / health over stdio
+```
+
+## How it works
+
+1. **Index** (read-only) — walk the project; classify each file; extract **symbols, imports
+   and calls** — Python via the stdlib `ast` (zero-deps core), and **JS/TS/Go/Rust/Java via
+   the optional `[treesitter]` extra**, both feeding one cross-language call graph; extract
+   **doc references** (markdown links, `[[wikilinks]]`, and **plain path mentions in prose** —
+   the part generic tools miss); pull out **decision ids** (`ADR-N`/`RFC-N`/`D-X-N`); add **git
+   sessions**. Everything lands in one typed graph with indexed adjacency, so queries are
+   O(degree), not O(edges).
+2. **Rank** — PageRank over the type-weighted, undirected graph; personalised PageRank for
+   task-aware queries.
+3. **Serve** — compact, contents-free rows, selected to fit a token budget. An assistant
+   queries; a human reads the digest.
+4. **Stay fresh** — a content-hash manifest diffs the tree on every `gate`, so drift is loud.
+
+The graph never duplicates file contents; `.veridge/` is derived and always regenerable.
+
+## Design principles (please keep these intact)
+
+**read-only · zero-deps core · low-token · ranked · deterministic.** Determinism matters: nodes
+and edges are sorted on serialization, so `graph.json` is reproducible and diffs are clean.
+
+## Status & roadmap
+
+Alpha (v0.1). Working today: the unified graph (files + symbols + areas + decisions +
+sessions), **multi-language symbols** (Python in the core; JS/TS/Go/Rust/Java via the optional
+`[treesitter]` extra), the PageRank ranking, the token-budgeted `focus` query, **`veridge
+impact`** (deterministic blast-radius, incl. `--diff` mode), **deterministic comprehension**
+(`map` layers, `veridge tour`, `veridge why`), the anti-drift gate, the CLI and the optional MCP
+server. **Next up:** a human viewer, then watch-mode freshness. See the full plan in
+[ROADMAP.md](ROADMAP.md).
+
+## Development
+
+```bash
+pip install -e ".[dev,mcp,treesitter]"
+ruff check veridge tests
+pytest -q
+```
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the design principles
+(read-only, zero-deps core, low-token, ranked, deterministic).
+
+## License
+
+MIT.

veridge-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Veridge
+
+[![CI](https://github.com/galimar/veridge/actions/workflows/ci.yml/badge.svg)](https://github.com/galimar/veridge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-none-success.svg)](pyproject.toml)
+
+**The always-fresh, low-token map of a *whole* project** — documents, code (down to the
+function/class), decisions and work sessions — unified in one typed graph, **ranked by what
+matters**, and served both to an AI assistant (as the minimal relevant context) and to a human.
+
+> *Veridge* fuses **veridical** (truthful, verified) with **ridge** — the crest line that runs
+> through and connects a whole terrain. That's what it builds: the *true, always-fresh backbone*
+> of how a project fits together — the structural through-line you and your assistant navigate by.
+
+---
+
+## Why it exists
+
+A project's knowledge lives in three places that drift apart: the **code**, the **documents**
+(designs, decisions, notes) and the **history** of how it got here. As it grows, keeping a
+mental model of how everything connects gets harder — and an AI assistant loses the thread
+between one session and the next, so every session restarts by re-reading and re-searching
+files. That is slow, incomplete, and burns tokens repeatedly.
+
+Veridge builds the project's graph **once** and keeps it fresh, then answers questions about it
+in a few hundred tokens. It unifies documents, code (down to the symbol), decisions and sessions
+in one map, **ranks** it so an answer is the *relevant* slice rather than everything, and serves
+that slice within a token budget — to an AI assistant and to a human alike.
+
+## What makes it different
+
+| Pillar | What it means |
+|---|---|
+| **One unified graph** | files **+ symbols** (functions/classes) **+ areas + decisions + git sessions** — code, docs and history in a single map. |
+| **Symbol-level, with a real call graph** | Python is parsed with the stdlib `ast` into a `defines`/`imports`/`calls` graph. Other languages plug in via the optional `[treesitter]` extra. |
+| **Ranked by relevance** | global **PageRank** ("what matters in this project") and **personalised PageRank** ("what matters *for this task*"). |
+| **Token-budgeted, task-aware** | `veridge focus "<task>"` returns the **minimal relevant subgraph within a token budget** — relevant context, not the whole repo. |
+| **Anti-drift gate** | content-hash freshness: refuses to call the map "fine" while something is stale, broken or orphaned. |
+| **Zero infrastructure** | the core runs on the **Python standard library alone** — no DB, no embeddings, no server. Read-only on your sources. |
+| **MCP-first** | the same ranked, budgeted queries are exposed to MCP-aware assistants behind an optional extra. |
+
+It is **not a RAG system**: no embeddings, no vector store, no LLM to build the graph. It maps
+*structure* and *importance*, which makes it complementary to RAG and purpose-built for one
+thing: **the cheapest accurate context for orienting on a project.**
+
+## Install
+
+```bash
+pip install -e .                      # from a clone
+pip install -e ".[mcp]"               # + optional MCP server
+pip install -e ".[treesitter]"        # + symbol-level JS/TS/Go/Rust/Java parsing
+```
+
+Requires Python 3.10+. Runtime dependencies of the core: **none**.
+
+## Quickstart
+
+```bash
+veridge build  .                 # index -> .veridge/graph.json (+ manifest)
+veridge map    .                 # PageRank-ranked digest: areas, sizes, what matters
+veridge focus  "<task>" .        # the signature query: minimal relevant subgraph, budgeted
+veridge impact src/util.py .     # blast-radius: what a change here affects (ranked, budgeted)
+veridge impact --diff .          # blast-radius of your current working changes (vs git HEAD)
+veridge tour   .                 # dependency-ordered reading tour of the key files
+veridge why    src/cli.py src/model.py .   # shortest typed path between two nodes
+veridge find   greet .           # find nodes (files or symbols) by name/path
+veridge neighbors src/util.py .  # a node and its typed connections
+veridge gate   .                 # anti-drift: broken refs, stale files, orphans
+veridge stats  .                 # counts by node/edge type
+```
+
+`veridge map` also groups files by **architectural layer** (entrypoint / api / service / core /
+data / ui / util / tests / config / docs) — inferred heuristically, no LLM.
+
+### The signature query: `focus`
+
+Give it a task, a file, or a symbol name and a token budget. It seeds a **personalised
+PageRank** on whatever the query matches, then admits the highest-ranked nodes until the
+budget is spent — returning exactly the context worth loading, and nothing else:
+
+```text
+$ veridge focus "personalised pagerank ranking" . --budget 400
+focus 'personalised pagerank ranking' · 24 nodes · ~391/400 tokens
+  seeds: veridge/rank.py#pagerank, tests/test_rank_budget.py#test_personalised_pagerank...
+  0.1487  veridge/rank.py#pagerank             [symbol, deg 8]
+  0.0334  veridge/query.py#focus               [symbol, deg 10]
+  0.0289  veridge/query.py#project_map         [symbol, deg 9]
+  0.0243  veridge/budget.py                    [file,   deg 8]
+  ...
+```
+
+### Blast-radius: `impact`
+
+"If I change this, what breaks — and what's the minimal context to review it safely?" That's
+*reverse reachability* over the call/import/reference graph, so Veridge answers it **for free
+and exactly** — no LLM call, no token cost. The affected set is ranked by a proximity-weighted
+PageRank and trimmed to a token budget, so even a hub with hundreds of dependents returns its
+most important ones:
+
+```text
+$ veridge impact veridge/model.py . --budget 300
+impact (dependents) of 'veridge/model.py' · 82 affected by
+  showing 20 · ~290/300 tokens
+  0.0256  d2  veridge/query.py#impact     [symbol]
+  0.0239  d1  veridge/query.py            [file]
+  0.0226  d1  veridge/cli.py              [file]
+  ...
+```
+
+`d1`/`d2` is the propagation distance. Use `--diff` to seed from your working changes
+(`git diff --name-only HEAD`) — "the blast-radius of what I'm about to commit" — or `--deps` to
+invert the question (what the seed *relies on*).
+
+Same idea over MCP:
+
+```bash
+pip install -e ".[mcp]"
+veridge-mcp .      # serves project_map / focus / impact / find / neighbors / health over stdio
+```
+
+## How it works
+
+1. **Index** (read-only) — walk the project; classify each file; extract **symbols, imports
+   and calls** — Python via the stdlib `ast` (zero-deps core), and **JS/TS/Go/Rust/Java via
+   the optional `[treesitter]` extra**, both feeding one cross-language call graph; extract
+   **doc references** (markdown links, `[[wikilinks]]`, and **plain path mentions in prose** —
+   the part generic tools miss); pull out **decision ids** (`ADR-N`/`RFC-N`/`D-X-N`); add **git
+   sessions**. Everything lands in one typed graph with indexed adjacency, so queries are
+   O(degree), not O(edges).
+2. **Rank** — PageRank over the type-weighted, undirected graph; personalised PageRank for
+   task-aware queries.
+3. **Serve** — compact, contents-free rows, selected to fit a token budget. An assistant
+   queries; a human reads the digest.
+4. **Stay fresh** — a content-hash manifest diffs the tree on every `gate`, so drift is loud.
+
+The graph never duplicates file contents; `.veridge/` is derived and always regenerable.
+
+## Design principles (please keep these intact)
+
+**read-only · zero-deps core · low-token · ranked · deterministic.** Determinism matters: nodes
+and edges are sorted on serialization, so `graph.json` is reproducible and diffs are clean.
+
+## Status & roadmap
+
+Alpha (v0.1). Working today: the unified graph (files + symbols + areas + decisions +
+sessions), **multi-language symbols** (Python in the core; JS/TS/Go/Rust/Java via the optional
+`[treesitter]` extra), the PageRank ranking, the token-budgeted `focus` query, **`veridge
+impact`** (deterministic blast-radius, incl. `--diff` mode), **deterministic comprehension**
+(`map` layers, `veridge tour`, `veridge why`), the anti-drift gate, the CLI and the optional MCP
+server. **Next up:** a human viewer, then watch-mode freshness. See the full plan in
+[ROADMAP.md](ROADMAP.md).
+
+## Development
+
+```bash
+pip install -e ".[dev,mcp,treesitter]"
+ruff check veridge tests
+pytest -q
+```
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the design principles
+(read-only, zero-deps core, low-token, ranked, deterministic).
+
+## License
+
+MIT.

veridge-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "veridge"
+dynamic = ["version"]
+description = "The always-fresh, low-token map of a whole project — docs, code (to the symbol), decisions — ranked by what matters and served to AI and humans alike."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["knowledge-graph", "code-graph", "ai-agents", "context", "mcp", "pagerank", "repo-map"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.4"]
+mcp = ["mcp>=1.2"]
+# Optional: symbol-level parsing for languages beyond Python's stdlib `ast`.
+treesitter = ["tree-sitter>=0.21", "tree-sitter-language-pack>=0.2"]
+
+[project.scripts]
+veridge = "veridge.cli:main"
+veridge-mcp = "veridge.mcp_server:main"
+
+[tool.setuptools]
+packages = ["veridge"]
+
+[tool.setuptools.dynamic]
+version = { attr = "veridge.__version__" }
+
+[tool.setuptools.package-data]
+veridge = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

veridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

veridge-0.1.0/tests/test_cli.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from veridge import cli
+
+
+def test_build_then_map(project, capsys):
+    assert cli.main(["build", str(project)]) == 0
+    assert (project / ".veridge" / "graph.json").is_file()
+    assert cli.main(["map", str(project)]) == 0
+    out = capsys.readouterr().out
+    assert "most important (PageRank)" in out
+
+
+def test_focus_cli(project, capsys):
+    cli.main(["build", str(project)])
+    assert cli.main(["focus", "util", str(project), "--budget", "600"]) == 0
+    out = capsys.readouterr().out
+    assert "focus 'util'" in out
+    assert "src/util.py" in out
+
+
+def test_impact_cli(project, capsys):
+    cli.main(["build", str(project)])
+    assert cli.main(["impact", "src/util.py", str(project), "--budget", "2000"]) == 0
+    out = capsys.readouterr().out
+    assert "impact (dependents)" in out
+    assert "src/app.py" in out
+
+
+def test_impact_cli_deps_direction(project, capsys):
+    cli.main(["build", str(project)])
+    assert cli.main(["impact", "src/app.py#run", str(project), "--deps", "--json"]) == 0
+    out = capsys.readouterr().out
+    assert '"dependencies"' in out
+    assert "src/util.py#greet" in out
+
+
+def test_gate_cli_red_on_broken(project, capsys):
+    cli.main(["build", str(project)])
+    rc = cli.main(["gate", str(project)])
+    out = capsys.readouterr().out
+    assert "broken references: 1" in out
+    assert rc == 1
+
+
+def test_find_cli(project, capsys):
+    cli.main(["build", str(project)])
+    cli.main(["find", "greet", str(project)])
+    assert "src/util.py#greet" in capsys.readouterr().out
+
+
+def test_map_json(project, capsys):
+    cli.main(["build", str(project)])
+    assert cli.main(["map", str(project), "--json"]) == 0
+    out = capsys.readouterr().out
+    assert '"most_important"' in out
+    assert '"by_layer"' in out
+
+
+def test_why_cli(project, capsys):
+    cli.main(["build", str(project)])
+    assert cli.main(["why", "src/app.py", "src/util.py", str(project)]) == 0
+    out = capsys.readouterr().out
+    assert "imports" in out
+
+
+def test_tour_cli(project, capsys):
+    cli.main(["build", str(project)])
+    assert cli.main(["tour", str(project), "--budget", "3000"]) == 0
+    out = capsys.readouterr().out
+    assert "tour of" in out
+    assert "src/util.py" in out

veridge-0.1.0/tests/test_freshness_store.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from veridge import store
+from veridge.freshness import build_manifest, diff_manifest, evaluate, index
+
+
+def test_manifest_diff_detects_change(project):
+    m1 = build_manifest(project)
+    (project / "src" / "util.py").write_text("def greet(n):\n    return n\n", encoding="utf-8")
+    (project / "new.md").write_text("new\n", encoding="utf-8")
+    m2 = build_manifest(project)
+    d = diff_manifest(m1, m2)
+    assert "new.md" in d["added"]
+    assert "src/util.py" in d["changed"]
+
+
+def test_gate_reports_broken_and_orphans(graph, project):
+    m = build_manifest(project)
+    rep = evaluate(graph, m, m)
+    assert rep.stale_count == 0
+    assert ("README.md", "src/missing.py") in rep.broken
+    assert "config.toml" in rep.orphans
+    assert rep.ok is False  # a broken ref keeps the gate red
+
+
+def test_gate_ok_when_clean(project):
+    # A project with no broken refs and a matching manifest is green.
+    (project / "README.md").write_text("# clean\n", encoding="utf-8")
+    g, m = index(project)
+    rep = evaluate(g, m, m)
+    assert rep.broken == []
+    assert rep.ok is True
+
+
+def test_store_roundtrip(graph, project):
+    _, m = index(project)
+    store.save(project, graph, m)
+    g2 = store.load_graph(project)
+    m2 = store.load_manifest(project)
+    assert g2 is not None and m2 is not None
+    assert set(g2.nodes) == set(graph.nodes)
+    assert g2.degree("src/util.py") == graph.degree("src/util.py")
+
+
+def test_load_missing_is_none(tmp_path):
+    assert store.load_graph(tmp_path) is None
+    assert store.load_manifest(tmp_path) is None

veridge-0.1.0/tests/test_impact.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from veridge import query
+from veridge.impact import dependencies, dependents, expand_seed
+
+
+def test_expand_seed_lifts_both_ways(graph):
+    # A file seed pulls in the symbols it defines.
+    assert "src/util.py#greet" in expand_seed(graph, "src/util.py")
+    # A symbol seed pulls in its defining file.
+    assert "src/util.py" in expand_seed(graph, "src/util.py#greet")
+
+
+def test_dependents_reverse_reachability(graph):
+    affected = dependents(graph, expand_seed(graph, "src/util.py"))
+    # Direct dependents of util / greet.
+    assert affected.get("src/app.py") == 1          # imports util
+    assert affected.get("docs/guide.md") == 1       # references util in prose
+    assert affected.get("src/app.py#run") == 1      # calls greet
+    # Transitive: callers of run are two hops out.
+    assert affected.get("src/app.py#App.start") == 2
+
+
+def test_dependencies_forward(graph):
+    deps = dependencies(graph, expand_seed(graph, "src/app.py#run"))
+    assert "src/util.py#greet" in deps  # run calls greet
+    assert "src/util.py" in deps        # app.py imports util.py
+
+
+def test_query_impact_ranked_and_budgeted(graph):
+    res = query.impact(graph, "src/util.py", budget_tokens=4000)
+    ids = {r["id"] for r in res["nodes"]}
+    assert res["total_affected"] >= 5
+    assert {"src/app.py", "src/app.py#run", "docs/guide.md"} <= ids
+    assert res["used_tokens"] <= 4000
+    # Every shown node carries its distance and rank.
+    assert all("dist" in r and "score" in r for r in res["nodes"])
+
+
+def test_query_impact_hops_cap(graph):
+    near = query.impact(graph, "src/util.py", hops=1, budget_tokens=4000)
+    ids = {r["id"] for r in near["nodes"]}
+    assert "src/app.py#run" in ids               # distance 1
+    assert "src/app.py#App.start" not in ids     # distance 2, excluded by hops=1
+
+
+def test_query_impact_budget_trims(graph):
+    small = query.impact(graph, "src/util.py", budget_tokens=15)
+    big = query.impact(graph, "src/util.py", budget_tokens=4000)
+    assert len(small["nodes"]) < len(big["nodes"])
+
+
+def test_query_impact_leaf_is_safe(graph):
+    # Nothing points at the README, so changing it has no dependents.
+    res = query.impact(graph, "README.md")
+    assert res["total_affected"] == 0
+    assert "safe to change" in res["note"]
+
+
+def test_query_impact_seed_by_name(graph):
+    res = query.impact(graph, "greet", budget_tokens=4000)
+    ids = {r["id"] for r in res["nodes"]}
+    assert "src/app.py#run" in ids  # resolved 'greet' -> its callers
+
+
+def test_query_impact_explicit_seed_ids_diff_mode(graph):
+    # Simulates --diff: seeds handed in directly (e.g. from `git diff --name-only`).
+    res = query.impact(graph, "diff", seed_ids=["src/util.py"], budget_tokens=4000)
+    assert res["total_affected"] >= 5
+    assert any(r["id"] == "src/app.py" for r in res["nodes"])