graphnav 1.2.3__tar.gz → 1.3.0__tar.gz

{graphnav-1.2.3/graphnav.egg-info → graphnav-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphnav
-Version: 1.2.3
+Version: 1.3.0
 Summary: Knowledge-graph context injection for AI coding agents in monorepos
 License-Expression: MIT
 Requires-Python: >=3.11

{graphnav-1.2.3 → graphnav-1.3.0}/README.md

@@ -18,6 +18,7 @@ GraphNav solves this by:
 
 ## GraphNav Core Features
 
+- **Always fresh, automatically** — when source files change, the next graph query detects it and rebuilds the graph in the background. No daemon, no manual re-runs, nothing to remember.
 - **Token-budgeted context packs** — `graphnav context "<task>"` returns only the relevant code, inline, with no LLM call.
 - **Native MCP tools** — `graphnav serve` exposes the graph to agents over the Model Context Protocol, refreshed automatically when the graph changes.
 - **Graph-aware ranking** — BM25 plus relation-weighted call-edge expansion and a git-recency nudge, so the file you actually need to edit surfaces even when its text doesn't match the query.
@@ -40,7 +41,7 @@ That's the whole setup. Run `graphnav` from your project root and it:
 2. Builds the knowledge graph
 3. Writes the agent instruction files
 
-Then open the repo in your AI coding tool and start working. **There is nothing else to run.**
+Then open the repo in your AI coding tool and start working. **There is nothing else to run — ever.** When you edit files, the next graph query (from you or your agent) automatically rebuilds the graph in the background, so it never goes stale. Disable with `auto_rebuild = false` under `[mono]` or `GRAPHNAV_NO_AUTO_REBUILD=1`.
 
 Requires Python ≥ 3.11. Pulls `graphifyy` (the `graphify` binary) automatically — including under `pipx`, `--user`, and virtualenv installs.
 
@@ -63,7 +64,7 @@ After running `graphnav`, every AI agent in the repo has access to:
 ### Optional
 
 ```bash
-graphnav watch     # keep the graph live as you edit
+graphnav watch     # eager mode: rebuild on every save instead of at query time
 graphnav doctor    # diagnose the setup if something looks wrong
 ```
 
@@ -308,6 +309,7 @@ Place a `config.toml` in the project root (or pass `--config PATH`):
 ```toml
 [mono]
 graphify_backend = "claude"        # LLM backend for extraction
+auto_rebuild = true                # rebuild the graph in the background when queries find it stale
 watch_poll_interval = 3.0          # seconds between mtime checks in watch mode
 context_budget_tokens = 2000       # token budget for graphnav context output
 context_top_files = 8              # max files returned by context command

{graphnav-1.2.3 → graphnav-1.3.0}/codex_graph/cli.py

@@ -104,6 +104,7 @@ def _run_context_command(argv: list[str]) -> None:
             "task": task,
             "skip_patterns": cfg.graph.skip_patterns,
             "query_cfg": cfg.query,
+            "auto_rebuild": cfg.mono.auto_rebuild,
         }
         if args.files is not None:
             kwargs["top_files"] = args.files
@@ -129,6 +130,7 @@ def _run_graph_query_command(kind: str, argv: list[str]) -> None:
 
     cfg = load_config(args.config)
     root = os.path.abspath(args.root)
+    multirepo.maybe_auto_rebuild(root, enabled=cfg.mono.auto_rebuild)
     graph_path = multirepo._overarching_graph_path(root)
     if not os.path.exists(graph_path):
         print(f"Error: no knowledge graph at {graph_path}. Run `graphnav map` first.", file=sys.stderr)
@@ -137,7 +139,7 @@ def _run_graph_query_command(kind: str, argv: list[str]) -> None:
     if kind == "impact":
         from codex_graph.mcp_server import GraphTools
 
-        tools = GraphTools(root, cfg.graph.skip_patterns, query_cfg=cfg.query)
+        tools = GraphTools(root, cfg.graph.skip_patterns, query_cfg=cfg.query, auto_rebuild=False)
         print(tools.impact(args.term))
         sys.exit(0)
 

{graphnav-1.2.3 → graphnav-1.3.0}/codex_graph/config.py

@@ -51,6 +51,7 @@ class MonoConfig:
     context_budget_tokens: int = 2000
     context_top_files: int = 8
     extra_skip_dirs: list[str] = field(default_factory=list)
+    auto_rebuild: bool = True
 
 
 @dataclass
@@ -129,6 +130,7 @@ def _apply_toml(cfg: Config, data: dict, warnings: list[str] | None = None) -> C
             context_budget_tokens=m.get("context_budget_tokens", cfg.mono.context_budget_tokens),
             context_top_files=m.get("context_top_files", cfg.mono.context_top_files),
             extra_skip_dirs=m.get("extra_skip_dirs", cfg.mono.extra_skip_dirs),
+            auto_rebuild=m.get("auto_rebuild", cfg.mono.auto_rebuild),
         )
     return cfg
 
@@ -163,6 +165,12 @@ def _coerce_types(cfg: Config, warnings: list[str]) -> None:
             if isinstance(w, bool) or not isinstance(w, (int, float)):
                 warnings.append(f"query.edge_relation_weights.{rel} has invalid value {w!r} — ignoring")
                 del cfg.query.edge_relation_weights[rel]
+    for section, key in (("mono", "auto_rebuild"), ("context", "show_scores")):
+        value = getattr(getattr(cfg, section), key)
+        if not isinstance(value, bool):
+            fallback = getattr(getattr(Config(), section), key)
+            warnings.append(f"{section}.{key} must be true or false — using default {fallback}")
+            setattr(getattr(cfg, section), key, fallback)
     for section, key in (("mono", "marker_files"), ("mono", "extra_skip_dirs"), ("graph", "skip_patterns"), ("codex", "extra_args")):
         value = getattr(getattr(cfg, section), key)
         if not isinstance(value, list) or any(not isinstance(v, str) for v in value):

{graphnav-1.2.3 → graphnav-1.3.0}/codex_graph/mcp_server.py

@@ -8,7 +8,11 @@ from codex_graph import GraphNotFoundError
 from codex_graph.config import QueryConfig, load_config
 from codex_graph.graph_cache import DEFAULT_PACK_SKIP_PATTERNS, load_bundle
 from codex_graph.graph_nav import GraphNav
-from codex_graph.multirepo import _overarching_graph_path, build_context_pack_inline
+from codex_graph.multirepo import (
+    _overarching_graph_path,
+    build_context_pack_inline,
+    maybe_auto_rebuild,
+)
 
 MAX_REGION_LINES = 200
 
@@ -32,10 +36,12 @@ class GraphTools:
         root: str,
         skip_patterns: list[str] | None = None,
         query_cfg: QueryConfig | None = None,
+        auto_rebuild: bool = True,
     ):
         self.root = os.path.abspath(root)
         self.skip_patterns = skip_patterns or list(DEFAULT_PACK_SKIP_PATTERNS)
         self.query_cfg = query_cfg or QueryConfig()
+        self.auto_rebuild = auto_rebuild
         self.graph_path = _overarching_graph_path(self.root)
 
     @property
@@ -53,10 +59,11 @@ class GraphTools:
     def graph_context(self, task: str) -> str:
         return build_context_pack_inline(
             root=self.root, task=task, skip_patterns=self.skip_patterns,
-            query_cfg=self.query_cfg,
+            query_cfg=self.query_cfg, auto_rebuild=self.auto_rebuild,
         )
 
     def graph_find(self, query: str) -> str:
+        maybe_auto_rebuild(self.root, enabled=self.auto_rebuild)
         if self.nav is None:
             return _NO_GRAPH
         hits = self.nav.find_symbols(query, k=8)
@@ -69,6 +76,7 @@ class GraphTools:
         return "\n".join(lines)
 
     def graph_neighbors(self, symbol: str) -> str:
+        maybe_auto_rebuild(self.root, enabled=self.auto_rebuild)
         if self.nav is None:
             return _NO_GRAPH
         r = self.nav.neighbors(symbol)
@@ -96,6 +104,7 @@ class GraphTools:
             return f"error: {exc}"
 
     def impact(self, symbol: str) -> str:
+        maybe_auto_rebuild(self.root, enabled=self.auto_rebuild)
         if self.nav is None:
             return _NO_GRAPH
         r = self.nav.neighbors(symbol)
@@ -130,7 +139,10 @@ def serve(root: str = ".", config_path: str | None = None) -> int:
         return 1
 
     cfg = load_config(config_path)
-    tools = GraphTools(os.path.abspath(root), cfg.graph.skip_patterns, query_cfg=cfg.query)
+    tools = GraphTools(
+        os.path.abspath(root), cfg.graph.skip_patterns, query_cfg=cfg.query,
+        auto_rebuild=cfg.mono.auto_rebuild,
+    )
     server = FastMCP("graphnav")
 
     @server.tool()

{graphnav-1.2.3 → graphnav-1.3.0}/codex_graph/multirepo.py

@@ -308,6 +308,81 @@ def run_extract(
     return _stream_proc(proc, timeout)
 
 
+AUTO_REBUILD_COOLDOWN = 60.0
+
+
+def _newest_source_mtime(root: str, max_depth: int = 4) -> float:
+    newest = 0.0
+    base = root.rstrip(os.sep).count(os.sep)
+    for dirpath, dirnames, filenames in os.walk(root):
+        depth = dirpath.count(os.sep) - base
+        if depth >= max_depth:
+            dirnames[:] = []
+        else:
+            dirnames[:] = [
+                d for d in dirnames
+                if d not in SKIP_DIRS and not d.startswith(".")
+            ]
+        for fn in filenames:
+            if os.path.splitext(fn)[1] in SOURCE_EXTENSIONS:
+                try:
+                    mt = os.stat(os.path.join(dirpath, fn)).st_mtime
+                except OSError:
+                    continue
+                if mt > newest:
+                    newest = mt
+    return newest
+
+
+def graph_is_stale(root: str) -> bool:
+    try:
+        graph_mtime = os.stat(_overarching_graph_path(root)).st_mtime
+    except OSError:
+        return True
+    return _newest_source_mtime(root) > graph_mtime + 1.0
+
+
+def maybe_auto_rebuild(root: str, enabled: bool = True) -> bool:
+    if not enabled or os.environ.get("GRAPHNAV_NO_AUTO_REBUILD") == "1":
+        return False
+    root = os.path.abspath(root)
+    if not graph_is_stale(root):
+        return False
+    out_dir = os.path.join(root, "graphify-out")
+    try:
+        os.makedirs(out_dir, exist_ok=True)
+    except OSError:
+        return False
+    pid_path = os.path.join(out_dir, ".graphnav-rebuild.pid")
+    try:
+        st = os.stat(pid_path)
+        with open(pid_path) as f:
+            pid = int(f.read().strip() or 0)
+        if pid > 0:
+            try:
+                os.kill(pid, 0)
+                return False
+            except OSError:
+                pass
+        if time.time() - st.st_mtime < AUTO_REBUILD_COOLDOWN:
+            return False
+    except (OSError, ValueError):
+        pass
+    log_path = os.path.join(out_dir, "auto-rebuild.log")
+    try:
+        with open(log_path, "ab") as log:
+            proc = subprocess.Popen(
+                [sys.executable, "-m", "codex_graph.cli", "map", "--root", root],
+                stdout=log, stderr=log, start_new_session=True,
+                env=_build_subprocess_env(root),
+            )
+        with open(pid_path, "w") as f:
+            f.write(str(proc.pid))
+        return True
+    except OSError:
+        return False
+
+
 def _overarching_graph_path(root: str) -> str:
     return os.path.join(root, "graphify-out", "graph.json")
 
@@ -666,9 +741,18 @@ def build_context_pack(
     from codex_graph.graph_query import query_files
 
     root = os.path.abspath(root)
+    if mono_cfg is None:
+        mono_cfg = MonoConfig()
+    rebuild_started = maybe_auto_rebuild(root, enabled=mono_cfg.auto_rebuild)
     overarching_path = _overarching_graph_path(root)
     if not os.path.exists(overarching_path):
         rel = os.path.relpath(overarching_path, root)
+        if rebuild_started:
+            return (
+                f"# Context for: {task}\n\n"
+                "Knowledge graph is being built automatically in the background — "
+                "retry this in ~30s.\n"
+            )
         return (
             f"# Context for: {task}\n\n"
             f"No knowledge graph found at {rel}.\n"
@@ -679,8 +763,6 @@ def build_context_pack(
         skip_patterns = list(DEFAULT_PACK_SKIP_PATTERNS)
     if query_cfg is None:
         query_cfg = QueryConfig()
-    if mono_cfg is None:
-        mono_cfg = MonoConfig()
 
     degraded = False
     try:
@@ -708,6 +790,8 @@ def build_context_pack(
     note = staleness_note(root)
     if note:
         out_lines += [note, ""]
+    if rebuild_started:
+        out_lines += ["_Source files changed — automatic graph rebuild started in the background._", ""]
     if degraded:
         out_lines.append(
             "_Knowledge graph could not be read (corrupt or invalid graph.json) — "
@@ -787,14 +871,22 @@ def _extract_code_windows(abs_path, lines_wanted, before=2, after=14, max_lines=
 
 
 def build_context_pack_inline(
-    root, task, top_files=3, budget_tokens=2500, skip_patterns=None, query_cfg=None
+    root, task, top_files=3, budget_tokens=2500, skip_patterns=None, query_cfg=None,
+    auto_rebuild=True,
 ):
     from codex_graph.graph_cache import DEFAULT_PACK_SKIP_PATTERNS, load_bundle
     from codex_graph.graph_query import query_files
 
     root = os.path.abspath(root)
+    rebuild_started = maybe_auto_rebuild(root, enabled=auto_rebuild)
     overarching_path = _overarching_graph_path(root)
     if not os.path.exists(overarching_path):
+        if rebuild_started:
+            return (
+                f"# Context for: {task}\n\n"
+                "Knowledge graph is being built automatically in the background — "
+                "retry this in ~30s.\n"
+            )
         return f"# Context for: {task}\n\nNo knowledge graph found.\n"
     if skip_patterns is None:
         skip_patterns = list(DEFAULT_PACK_SKIP_PATTERNS)
@@ -827,6 +919,8 @@ def build_context_pack_inline(
     note = staleness_note(root)
     if note:
         out += [note, ""]
+    if rebuild_started:
+        out += ["_Source files changed — automatic graph rebuild started in the background._", ""]
     out.append(
         "## Relevant code (extracted from the knowledge graph — already in context, do not re-open these files)"
     )

{graphnav-1.2.3 → graphnav-1.3.0/graphnav.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphnav
-Version: 1.2.3
+Version: 1.3.0
 Summary: Knowledge-graph context injection for AI coding agents in monorepos
 License-Expression: MIT
 Requires-Python: >=3.11

{graphnav-1.2.3 → graphnav-1.3.0}/graphnav.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ graphnav.egg-info/dependency_links.txt
 graphnav.egg-info/entry_points.txt
 graphnav.egg-info/requires.txt
 graphnav.egg-info/top_level.txt
+tests/test_auto_rebuild.py
 tests/test_cli.py
 tests/test_config.py
 tests/test_doctor.py

{graphnav-1.2.3 → graphnav-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphnav"
-version = "1.2.3"
+version = "1.3.0"
 description = "Knowledge-graph context injection for AI coding agents in monorepos"
 license = "MIT"
 requires-python = ">=3.11"

graphnav-1.3.0/tests/test_auto_rebuild.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import os
+import time
+from unittest.mock import MagicMock
+
+import pytest
+
+from codex_graph import multirepo
+from codex_graph.config import load_config_report
+from codex_graph.multirepo import graph_is_stale, maybe_auto_rebuild
+from tests.conftest import write_graph
+
+
+@pytest.fixture
+def allow_auto(monkeypatch):
+    monkeypatch.delenv("GRAPHNAV_NO_AUTO_REBUILD", raising=False)
+
+
+@pytest.fixture
+def fake_popen(monkeypatch):
+    proc = MagicMock()
+    proc.pid = 99999999
+    popen = MagicMock(return_value=proc)
+    monkeypatch.setattr(multirepo.subprocess, "Popen", popen)
+    monkeypatch.setattr(multirepo, "_git_sha", lambda root: None)
+    monkeypatch.setattr("codex_graph.graph_cache._git_recency", lambda root: {})
+    return popen
+
+
+def _make_repo(tmp_path, stale: bool):
+    src = tmp_path / "app.py"
+    src.write_text("def main():\n    pass\n")
+    write_graph(tmp_path / "graphify-out" / "graph.json", [], [])
+    graph = tmp_path / "graphify-out" / "graph.json"
+    if stale:
+        os.utime(graph, (time.time() - 100, time.time() - 100))
+    else:
+        os.utime(src, (time.time() - 100, time.time() - 100))
+    return tmp_path
+
+
+class TestStaleness:
+    def test_missing_graph_is_stale(self, tmp_path):
+        (tmp_path / "app.py").write_text("x = 1\n")
+        assert graph_is_stale(str(tmp_path)) is True
+
+    def test_fresh_graph_not_stale(self, tmp_path):
+        _make_repo(tmp_path, stale=False)
+        assert graph_is_stale(str(tmp_path)) is False
+
+    def test_edited_source_is_stale(self, tmp_path):
+        _make_repo(tmp_path, stale=True)
+        assert graph_is_stale(str(tmp_path)) is True
+
+
+class TestMaybeAutoRebuild:
+    def test_spawns_on_stale(self, tmp_path, allow_auto, fake_popen):
+        _make_repo(tmp_path, stale=True)
+        assert maybe_auto_rebuild(str(tmp_path)) is True
+        fake_popen.assert_called_once()
+        argv = fake_popen.call_args[0][0]
+        assert argv[-2:] == ["--root", str(tmp_path)]
+        assert "map" in argv
+        pid_file = tmp_path / "graphify-out" / ".graphnav-rebuild.pid"
+        assert pid_file.read_text() == "99999999"
+
+    def test_no_spawn_when_fresh(self, tmp_path, allow_auto, fake_popen):
+        _make_repo(tmp_path, stale=False)
+        assert maybe_auto_rebuild(str(tmp_path)) is False
+        fake_popen.assert_not_called()
+
+    def test_no_spawn_when_disabled(self, tmp_path, allow_auto, fake_popen):
+        _make_repo(tmp_path, stale=True)
+        assert maybe_auto_rebuild(str(tmp_path), enabled=False) is False
+        fake_popen.assert_not_called()
+
+    def test_env_escape_hatch(self, tmp_path, monkeypatch, fake_popen):
+        monkeypatch.setenv("GRAPHNAV_NO_AUTO_REBUILD", "1")
+        _make_repo(tmp_path, stale=True)
+        assert maybe_auto_rebuild(str(tmp_path)) is False
+        fake_popen.assert_not_called()
+
+    def test_skips_when_rebuild_running(self, tmp_path, allow_auto, fake_popen):
+        _make_repo(tmp_path, stale=True)
+        pid_file = tmp_path / "graphify-out" / ".graphnav-rebuild.pid"
+        pid_file.write_text(str(os.getpid()))
+        assert maybe_auto_rebuild(str(tmp_path)) is False
+        fake_popen.assert_not_called()
+
+    def test_cooldown_after_dead_rebuild(self, tmp_path, allow_auto, fake_popen):
+        _make_repo(tmp_path, stale=True)
+        pid_file = tmp_path / "graphify-out" / ".graphnav-rebuild.pid"
+        pid_file.write_text("999999999")
+        assert maybe_auto_rebuild(str(tmp_path)) is False
+        fake_popen.assert_not_called()
+        old = time.time() - 120
+        os.utime(pid_file, (old, old))
+        assert maybe_auto_rebuild(str(tmp_path)) is True
+        fake_popen.assert_called_once()
+
+
+class TestPackNotes:
+    def test_inline_pack_notes_rebuild(self, tmp_path, allow_auto, fake_popen, monkeypatch):
+        _make_repo(tmp_path, stale=True)
+        write_graph(
+            tmp_path / "graphify-out" / "graph.json",
+            [{"id": "m", "label": "main", "source_file": "app.py",
+              "file_type": "code", "source_location": "L1", "community": 0}],
+            [],
+        )
+        graph = tmp_path / "graphify-out" / "graph.json"
+        os.utime(graph, (time.time() - 100, time.time() - 100))
+        pack = multirepo.build_context_pack_inline(str(tmp_path), "main")
+        assert "automatic graph rebuild started" in pack
+
+    def test_no_graph_pack_reports_building(self, tmp_path, allow_auto, fake_popen):
+        (tmp_path / "app.py").write_text("def main():\n    pass\n")
+        pack = multirepo.build_context_pack_inline(str(tmp_path), "main")
+        assert "being built automatically" in pack
+
+
+class TestConfigKnob:
+    def test_auto_rebuild_default_true(self):
+        cfg, _, _ = load_config_report()
+        assert cfg.mono.auto_rebuild is True
+
+    def test_auto_rebuild_from_toml(self, tmp_path, monkeypatch):
+        (tmp_path / "config.toml").write_text("[mono]\nauto_rebuild = false\n")
+        monkeypatch.chdir(tmp_path)
+        cfg, _, warnings = load_config_report()
+        assert cfg.mono.auto_rebuild is False
+        assert warnings == []
+
+    def test_wrong_typed_auto_rebuild(self, tmp_path, monkeypatch):
+        (tmp_path / "config.toml").write_text('[mono]\nauto_rebuild = "yes"\n')
+        monkeypatch.chdir(tmp_path)
+        cfg, _, warnings = load_config_report()
+        assert cfg.mono.auto_rebuild is True
+        assert any("true or false" in w for w in warnings)

{graphnav-1.2.3 → graphnav-1.3.0}/tests/test_cli.py

@@ -123,7 +123,7 @@ class TestContextCommand:
     def test_context_forwards_budget_and_files(self, tmp_path, monkeypatch):
         captured = {}
 
-        def fake_pack(root, task, skip_patterns=None, top_files=None, budget_tokens=None, query_cfg=None):
+        def fake_pack(root, task, skip_patterns=None, top_files=None, budget_tokens=None, query_cfg=None, **kw):
             captured["top_files"] = top_files
             captured["budget_tokens"] = budget_tokens
             return ""