graphnav 1.2.1__tar.gz → 1.2.3__tar.gz

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

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

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

@@ -27,13 +27,22 @@ GraphNav solves this by:
 
 ---
 
-## Install
+## Setup is one command
 
 ```bash
 pip install graphnav
+graphnav
 ```
 
-Requires Python ≥ 3.11. Pulls `graphifyy` (the `graphify` binary) automatically.
+That's the whole setup. Run `graphnav` from your project root and it:
+
+1. Auto-detects your project — a **single folder** or a **monorepo** of services
+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.**
+
+Requires Python ≥ 3.11. Pulls `graphifyy` (the `graphify` binary) automatically — including under `pipx`, `--user`, and virtualenv installs.
 
 **API key:** Place a `.env` file anywhere up the directory tree from your project (or inside any service subfolder). graphnav walks up and down to find it:
 
@@ -42,22 +51,7 @@ OPENAI_API_KEY=sk-...
 ANTHROPIC_KEY=sk-ant-...
 ```
 
----
-
-## Quickstart
-
-```bash
-# In your monorepo root — detects services, builds graphs, writes agent instructions
-graphnav map
-
-# Get a context pack for a task (free, no LLM, ~instant)
-graphnav context "add a critique scoring function to the coach"
-
-# Keep graphs live as you edit
-graphnav watch
-```
-
-After `map`, every AI agent in the repo has access to:
+After running `graphnav`, every AI agent in the repo has access to:
 
 - **`CLAUDE.md`** — picked up by Claude Code
 - **`AGENTS.md`** — picked up by OpenAI Codex CLI
@@ -66,13 +60,34 @@ After `map`, every AI agent in the repo has access to:
 - **`<service>/graphify-out/BRIDGES.md`** — exact cross-service call sites with line numbers
 - **`graphify-out/MONOREPO_MAP.md`** — overview of all services and their connections
 
+### Optional
+
+```bash
+graphnav watch     # keep the graph live as you edit
+graphnav doctor    # diagnose the setup if something looks wrong
+```
+
 ---
 
 ## Commands
 
+> **You only need `graphnav`.** Running it bare does the full setup (it runs `map` for you). `watch` and `doctor` are the only other commands you'd type by hand. Everything below `graphnav watch` — `context`, `serve`, `find`, `neighbors`, `impact` — is meant for your **AI agent** to call automatically (via the generated instruction files or the MCP server), not for you to run manually. They're documented here for completeness.
+
+### `graphnav` (just this)
+
+From your project root, run `graphnav` with no arguments. It auto-detects whether you have a single-folder project or a monorepo, builds the knowledge graph, writes all agent instruction files, and stops. This is the one command you run.
+
+```
+graphnav
+```
+
+For a single-folder project it maps the whole repo as one graph; for a monorepo it builds per-service graphs and cross-service bridges. Equivalent to running `graphnav map` explicitly.
+
+---
+
 ### `graphnav map`
 
-Builds the knowledge graph and generates all agent instruction files.
+The build step that bare `graphnav` runs for you. Builds the knowledge graph and generates all agent instruction files.
 
 ```
 graphnav map [--root PATH] [--backend BACKEND] [--dry-run]
@@ -212,7 +227,7 @@ It checks the `graphify` binary, the config file (and reports any validation war
 
 ### `graphnav` (no subcommand)
 
-If run with no arguments in a monorepo root, auto-detects services and runs `map` automatically. If a prompt is given, falls through to the context-injection path for the Codex CLI.
+Run with no arguments from any project root, it auto-detects the project shape (single folder or monorepo) and runs the full setup automatically. If a prompt is given, it falls through to the context-injection path for the Codex CLI.
 
 ---
 
@@ -344,7 +359,7 @@ ANTHROPIC_KEY=sk-ant-...
 Then:
 
 ```bash
-graphnav map          # one-time setup, or re-run after large refactors
+graphnav              # one-time setup, or re-run after large refactors
 graphnav watch        # optional: keep graphs live during active development
 ```
 

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

@@ -51,13 +51,16 @@ def _auto_map_if_needed(cfg_path: str | None) -> None:
 
     cfg = load_config(cfg_path)
     root = os.path.abspath(".")
-    services = multirepo.detect_services(root, cfg.mono.marker_files, cfg.mono.extra_skip_dirs)
+    services, single = multirepo.resolve_services(root, cfg.mono.marker_files, cfg.mono.extra_skip_dirs)
     if not services:
-        return
+        print("[graphnav] No source code found here. Run graphnav from your project's root directory.", file=sys.stderr)
+        sys.exit(1)
 
-    names = ", ".join(s.name for s in services)
-    print(f"[graphnav] Detected {len(services)} service(s): {names}")
-    print(f"[graphnav] Running 'graphnav map' to build knowledge graphs ...", file=sys.stderr)
+    if single:
+        print(f"[graphnav] Single project detected. Building knowledge graph ...", file=sys.stderr)
+    else:
+        names = ", ".join(s.name for s in services)
+        print(f"[graphnav] Detected {len(services)} service(s): {names}. Building knowledge graphs ...", file=sys.stderr)
     rc = multirepo.run_map(root=root, mono_cfg=cfg.mono)
     sys.exit(rc)
 
@@ -138,10 +141,17 @@ def _run_graph_query_command(kind: str, argv: list[str]) -> None:
         print(tools.impact(args.term))
         sys.exit(0)
 
-    nav = load_bundle(
-        graph_path, cfg.graph.skip_patterns,
-        relation_weights=cfg.query.edge_relation_weights, repo_root=root,
-    ).nav
+    import json as _json
+
+    try:
+        nav = load_bundle(
+            graph_path, cfg.graph.skip_patterns,
+            relation_weights=cfg.query.edge_relation_weights, repo_root=root,
+        ).nav
+    except (_json.JSONDecodeError, KeyError, OSError) as exc:
+        print(f"Error: could not read {graph_path} ({type(exc).__name__}: {exc}).", file=sys.stderr)
+        print("Run `graphnav map` to rebuild the graph.", file=sys.stderr)
+        sys.exit(2)
 
     if kind == "find":
         hits = nav.find_symbols(args.term, k=10)
@@ -216,16 +226,20 @@ def main() -> None:
     parser = argparse.ArgumentParser(
         prog="graphnav",
         description=(
-            "Codex CLI with knowledge-graph context injection for monorepos.\n\n"
-            "First-run (after pip install): just run 'graphnav' or 'graphnav map'\n"
-            "in your monorepo root — services are auto-detected and graphs are built.\n\n"
-            "Subcommands:\n"
-            "  map      Build per-service graphs and cross-service bridge notes\n"
-            "  watch    Keep graphs and bridge notes up-to-date as files change\n"
-            "  context  Print a token-budgeted context pack for a task (free, no LLM)\n"
-            "  serve    Run the MCP server so AI agents call the graph tools natively\n"
-            "  find     Find symbols by query; neighbors/impact show a symbol's blast radius\n"
-            "  doctor   Diagnose the setup (graphify binary, config, graph, API key, cache)"
+            "GraphNav — knowledge-graph context for AI coding agents.\n\n"
+            "Setup is ONE command. From your project root, just run:\n"
+            "    graphnav\n"
+            "It auto-detects your project (single folder or monorepo), builds the\n"
+            "knowledge graph, and writes the agent instruction files. Nothing else\n"
+            "to run — open the repo in your AI coding tool and start working.\n\n"
+            "Optional commands:\n"
+            "  watch    Keep the graph live as you edit\n"
+            "  doctor   Diagnose the setup if something looks wrong\n\n"
+            "Commands your AI agent calls for you (you rarely run these by hand):\n"
+            "  context  Token-budgeted context pack for a task (free, no LLM)\n"
+            "  serve    MCP server exposing the graph tools natively\n"
+            "  find / neighbors / impact   Symbol lookup and blast-radius queries\n"
+            "  map      The build step that `graphnav` runs for you"
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
@@ -243,8 +257,7 @@ def main() -> None:
     if not prompt:
         if sys.stdin.isatty():
             _auto_map_if_needed(args.config)
-            parser.print_help()
-            sys.exit(1)
+            return
         prompt = sys.stdin.read().strip()
     if not prompt:
         parser.print_help()
@@ -278,6 +291,10 @@ def main() -> None:
         except GraphNotFoundError as e:
             print(f"Error: {e}", file=sys.stderr)
             sys.exit(2)
+        except Exception as e:
+            print(f"Error: could not read {graph_path} ({type(e).__name__}: {e}).", file=sys.stderr)
+            print("Run `graphnav map` to rebuild the graph.", file=sys.stderr)
+            sys.exit(2)
 
         ranked = query_files(
             prompt,
@@ -311,5 +328,13 @@ def main() -> None:
         sys.exit(124)
 
 
+def entry() -> None:
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\n[graphnav] interrupted", file=sys.stderr)
+        sys.exit(130)
+
+
 if __name__ == "__main__":
-    main()
+    entry()

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

@@ -133,8 +133,47 @@ def _apply_toml(cfg: Config, data: dict, warnings: list[str] | None = None) -> C
     return cfg
 
 
+_NUMERIC_FIELDS = (
+    ("query", "top_k", int), ("query", "community_boost_weight", float),
+    ("query", "bm25_k1", float), ("query", "bm25_b", float),
+    ("query", "edge_boost_weight", float), ("query", "recency_boost_weight", float),
+    ("context", "max_file_chars", int),
+    ("codex", "timeout_seconds", int),
+    ("mono", "watch_poll_interval", float), ("mono", "context_budget_tokens", int),
+    ("mono", "context_top_files", int),
+)
+
+
+def _coerce_types(cfg: Config, warnings: list[str]) -> None:
+    defaults = Config()
+    for section, key, typ in _NUMERIC_FIELDS:
+        value = getattr(getattr(cfg, section), key)
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            fallback = getattr(getattr(defaults, section), key)
+            warnings.append(f"{section}.{key} has invalid value {value!r} — using default {fallback}")
+            setattr(getattr(cfg, section), key, fallback)
+        elif typ is int and not isinstance(value, int):
+            setattr(getattr(cfg, section), key, int(value))
+    if not isinstance(cfg.query.edge_relation_weights, dict):
+        warnings.append("query.edge_relation_weights must be a table — ignoring")
+        cfg.query.edge_relation_weights = {}
+    else:
+        for rel in list(cfg.query.edge_relation_weights):
+            w = cfg.query.edge_relation_weights[rel]
+            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", "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):
+            fallback = getattr(getattr(Config(), section), key)
+            warnings.append(f"{section}.{key} must be a list of strings — using default")
+            setattr(getattr(cfg, section), key, fallback)
+
+
 def _validate(cfg: Config) -> list[str]:
     warnings: list[str] = []
+    _coerce_types(cfg, warnings)
     if cfg.query.top_k < 1:
         warnings.append(f"query.top_k {cfg.query.top_k} clamped to 1")
         cfg.query.top_k = 1
@@ -192,12 +231,20 @@ def load_config_report(explicit_path: str | None = None) -> tuple[Config, str |
 
     source_path: str | None = None
     for path in candidates:
-        if os.path.exists(path):
+        if not os.path.exists(path):
+            continue
+        try:
             with open(path, "rb") as f:
                 data = tomllib.load(f)
-            cfg = _apply_toml(cfg, data, warnings)
+        except (tomllib.TOMLDecodeError, OSError) as exc:
+            warnings.append(f"could not parse {path} ({exc}) — using defaults")
             source_path = path
             break
+        if not explicit_path and not any(section in data for section in _SECTION_TYPES):
+            continue
+        cfg = _apply_toml(cfg, data, warnings)
+        source_path = path
+        break
     else:
         if explicit_path:
             print(f"Warning: config file not found: {explicit_path}", file=sys.stderr)

{graphnav-1.2.1 → graphnav-1.2.3}/codex_graph/doctor.py

@@ -11,8 +11,8 @@ from codex_graph.multirepo import (
     _graph_meta_path,
     _load_env_file,
     _overarching_graph_path,
-    detect_services,
     find_graphify,
+    resolve_services,
     staleness_note,
 )
 
@@ -104,9 +104,11 @@ def _check_api_key(root: str, cfg: Config) -> CheckResult:
 
 
 def _check_services(root: str, cfg: Config) -> CheckResult:
-    services = detect_services(root, cfg.mono.marker_files, cfg.mono.extra_skip_dirs)
+    services, single = resolve_services(root, cfg.mono.marker_files, cfg.mono.extra_skip_dirs)
     if not services:
-        return CheckResult("fail", "services", "no services detected — add code or marker files to subdirectories")
+        return CheckResult("fail", "services", "no source code found — run graphnav from your project root")
+    if single:
+        return CheckResult("ok", "services", "single project (whole repo mapped as one graph)")
     names = [s.name for s in services]
     shown = ", ".join(names[:MAX_SERVICE_NAMES_SHOWN])
     if len(names) > MAX_SERVICE_NAMES_SHOWN:

{graphnav-1.2.1 → graphnav-1.2.3}/codex_graph/graph_cache.py

@@ -149,7 +149,7 @@ def _build_bundle(
 ) -> GraphBundle:
     from codex_graph.multirepo import _symbols_by_file
 
-    with open(graph_path) as f:
+    with open(graph_path, encoding="utf-8") as f:
         graph = json.load(f)
     return GraphBundle(
         stamp=stamp,

{graphnav-1.2.1 → graphnav-1.2.3}/codex_graph/graph_nav.py

@@ -11,7 +11,7 @@ from codex_graph.graph_query import _tokenize
 class GraphNav:
     def __init__(self, graph_path: str, skip_patterns: list[str] | None = None, graph: dict | None = None):
         if graph is None:
-            with open(graph_path) as f:
+            with open(graph_path, encoding="utf-8") as f:
                 graph = json.load(f)
         self.skip = skip_patterns or []
         self._label_index = None
@@ -27,7 +27,10 @@ class GraphNav:
                 self.file2ids[sf].append(nid)
         self.in_edges: dict[object, list] = defaultdict(list)
         self.out_edges: dict[object, list] = defaultdict(list)
-        for e in graph.get("links", []):
+        links = graph.get("links")
+        if links is None:
+            links = graph.get("edges", [])
+        for e in links or []:
             s, t = e.get("source"), e.get("target")
             if s is None or t is None:
                 continue
@@ -104,12 +107,18 @@ class GraphNav:
         return hits
 
     def neighbors(self, symbol: str, k: int = 12) -> dict:
-        q = set(_tokenize(symbol))
-        best, best_ov = None, 0
-        for nid, n in self.id2node.items():
-            ov = len(q & set(_tokenize(n.get("label", ""))))
-            if ov > best_ov:
-                best, best_ov = nid, ov
+        exact = self._labels().get(symbol.lower())
+        if exact:
+            best = exact[0]
+        else:
+            q = set(_tokenize(symbol))
+            best, best_score = None, (0, 0.0)
+            for nid, n in self.id2node.items():
+                toks = set(_tokenize(n.get("label", "")))
+                ov = len(q & toks)
+                score = (ov, ov / (len(toks) or 1))
+                if score > best_score:
+                    best, best_score = nid, score
         fuzzy = False
         if best is None:
             fuzzy_ids = self._fuzzy_ids(symbol, n=1)

{graphnav-1.2.1 → graphnav-1.2.3}/codex_graph/graph_query.py

@@ -92,7 +92,7 @@ class GraphIndex:
         graph: dict | None = None,
     ):
         if graph is None:
-            with open(graph_path) as f:
+            with open(graph_path, encoding="utf-8") as f:
                 graph = json.load(f)
 
         nodes = graph.get("nodes", [])

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

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import os
 import sys
 
@@ -46,7 +47,7 @@ class GraphTools:
                 relation_weights=self.query_cfg.edge_relation_weights,
                 repo_root=self.root,
             ).nav
-        except GraphNotFoundError:
+        except (GraphNotFoundError, OSError, json.JSONDecodeError, KeyError):
             return None
 
     def graph_context(self, task: str) -> str:

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

@@ -4,6 +4,7 @@ import json
 import os
 import re
 import shutil
+import signal
 import subprocess
 import sys
 import threading
@@ -17,24 +18,80 @@ def find_graphify() -> str | None:
     path = shutil.which("graphify")
     if path:
         return path
-    candidate = os.path.join(os.path.dirname(sys.executable), "graphify")
-    if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
-        return candidate
+    exe = "graphify.exe" if os.name == "nt" else "graphify"
+    search_dirs = [os.path.dirname(sys.executable)]
+    import sysconfig
+
+    for scheme in sysconfig.get_scheme_names():
+        try:
+            d = sysconfig.get_path("scripts", scheme)
+        except Exception:
+            d = None
+        if d:
+            search_dirs.append(d)
+    seen: set[str] = set()
+    for d in search_dirs:
+        if not d or d in seen:
+            continue
+        seen.add(d)
+        candidate = os.path.join(d, exe)
+        if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+            return candidate
     return None
 
 
+def _any_subdir_has_marker(
+    root: str,
+    marker_files: list[str],
+    extra_skip_dirs: list[str] | None = None,
+) -> bool:
+    skip_dirs = SKIP_DIRS | frozenset(extra_skip_dirs or ())
+    try:
+        entries = os.listdir(root)
+    except OSError:
+        return False
+    for entry in entries:
+        abs_path = os.path.join(root, entry)
+        if not os.path.isdir(abs_path) or entry in skip_dirs or entry.startswith("."):
+            continue
+        if any(os.path.exists(os.path.join(abs_path, m)) for m in marker_files):
+            return True
+    return False
+
+
+def resolve_services(
+    root: str,
+    marker_files: list[str],
+    extra_skip_dirs: list[str] | None = None,
+) -> tuple[list[ServiceInfo], bool]:
+    if _any_subdir_has_marker(root, marker_files, extra_skip_dirs):
+        services = detect_services(root, marker_files, extra_skip_dirs)
+        if services:
+            return services, False
+    skip_dirs = SKIP_DIRS | frozenset(extra_skip_dirs or ())
+    if _has_source_files(root, skip_dirs=skip_dirs):
+        name = os.path.basename(os.path.abspath(root).rstrip(os.sep)) or "repo"
+        root_service = ServiceInfo(
+            name=name,
+            abs_path=root,
+            graph_path=_overarching_graph_path(root),
+        )
+        return [root_service], True
+    return [], False
+
+
 def _warn(msg: str) -> None:
     print(f"[graphnav] warning: {msg}", file=sys.stderr)
 
 
 def _write_if_changed(path: str, content: str) -> bool:
     try:
-        with open(path) as f:
+        with open(path, encoding="utf-8") as f:
             if f.read() == content:
                 return False
-    except OSError:
+    except (OSError, UnicodeDecodeError):
         pass
-    with open(path, "w") as f:
+    with open(path, "w", encoding="utf-8") as f:
         f.write(content)
     return True
 
@@ -68,7 +125,7 @@ def _find_env_file(start: str) -> str | None:
 def _parse_env_file(path: str) -> dict[str, str]:
     env_vars: dict[str, str] = {}
     try:
-        with open(path) as f:
+        with open(path, encoding="utf-8-sig") as f:
             for line in f:
                 line = line.strip()
                 if not line or line.startswith("#") or "=" not in line:
@@ -102,13 +159,22 @@ def _env_file_sources(root: str) -> list[str]:
     return sources
 
 
+_KEY_ALIASES = {
+    "ANTHROPIC_KEY": "ANTHROPIC_API_KEY",
+    "OPENAI_KEY": "OPENAI_API_KEY",
+    "GEMINI_KEY": "GEMINI_API_KEY",
+    "DEEPSEEK_KEY": "DEEPSEEK_API_KEY",
+}
+
+
 def _load_env_file(root: str) -> dict[str, str]:
     env_vars: dict[str, str] = {}
     for path in _env_file_sources(root):
         for key, value in _parse_env_file(path).items():
             env_vars.setdefault(key, value)
-    if "ANTHROPIC_KEY" in env_vars and "ANTHROPIC_API_KEY" not in env_vars:
-        env_vars["ANTHROPIC_API_KEY"] = env_vars["ANTHROPIC_KEY"]
+    for alias, canonical in _KEY_ALIASES.items():
+        if alias in env_vars and canonical not in env_vars:
+            env_vars[canonical] = env_vars[alias]
     return env_vars
 
 
@@ -280,7 +346,7 @@ def write_graph_meta(root: str) -> None:
     meta = {"built_at": time.strftime("%Y-%m-%dT%H:%M:%S"), "git_sha": _git_sha(root)}
     path = _graph_meta_path(root)
     os.makedirs(os.path.dirname(path), exist_ok=True)
-    with open(path, "w") as f:
+    with open(path, "w", encoding="utf-8") as f:
         json.dump(meta, f, indent=2)
 
 
@@ -289,7 +355,7 @@ def staleness_note(root: str) -> str:
     if not os.path.exists(path):
         return ""
     try:
-        with open(path) as f:
+        with open(path, encoding="utf-8") as f:
             meta = json.load(f)
     except (OSError, json.JSONDecodeError):
         return ""
@@ -335,7 +401,7 @@ def partition_graph(
     overarching_graph_path: str,
     services: list[ServiceInfo],
 ) -> dict[str, int]:
-    with open(overarching_graph_path) as f:
+    with open(overarching_graph_path, encoding="utf-8") as f:
         graph = json.load(f)
 
     service_names = {s.name for s in services}
@@ -378,7 +444,7 @@ def analyze_bridges(
     overarching_graph_path: str,
     services: list[ServiceInfo],
 ) -> dict[str, list[BridgeRow]]:
-    with open(overarching_graph_path) as f:
+    with open(overarching_graph_path, encoding="utf-8") as f:
         graph = json.load(f)
 
     service_names = {s.name for s in services}
@@ -471,7 +537,7 @@ def write_symbols_md(service: ServiceInfo) -> str:
     os.makedirs(out_dir, exist_ok=True)
     path = os.path.join(out_dir, "SYMBOLS.md")
     try:
-        with open(service.graph_path) as f:
+        with open(service.graph_path, encoding="utf-8") as f:
             graph = json.load(f)
     except (OSError, json.JSONDecodeError) as exc:
         _warn(f"could not read {service.graph_path} ({type(exc).__name__}) — symbols index will be empty")
@@ -553,7 +619,7 @@ def _write_managed_block(path: str, content: str) -> None:
     existing = ""
     if os.path.exists(path):
         try:
-            with open(path) as f:
+            with open(path, encoding="utf-8", errors="replace") as f:
                 existing = f.read()
         except OSError:
             existing = ""
@@ -697,7 +763,7 @@ def build_context_pack(
 
 def _extract_code_windows(abs_path, lines_wanted, before=2, after=14, max_lines=110):
     try:
-        with open(abs_path, errors="replace") as f:
+        with open(abs_path, encoding="utf-8", errors="replace") as f:
             src = f.read().splitlines()
     except OSError:
         return ""
@@ -808,7 +874,10 @@ def build_context_pack_inline(
     text = "\n".join(out) + "\n"
     char_budget = max(budget_tokens, 0) * 4
     if char_budget and len(text) > char_budget:
-        text = text[:char_budget].rstrip() + "\n```\n\n_(truncated to budget)_\n"
+        truncated = text[:char_budget].rstrip()
+        if truncated.count("```") % 2 == 1:
+            truncated += "\n```"
+        text = truncated + "\n\n_(truncated to budget)_\n"
     return text
 
 
@@ -816,9 +885,13 @@ def _refresh(
     root: str,
     services: list[ServiceInfo],
     overarching_graph_path: str,
+    single: bool = False,
 ) -> dict[str, list[BridgeRow]]:
-    partition_graph(overarching_graph_path, services)
-    bridges = analyze_bridges(overarching_graph_path, services)
+    if single:
+        bridges = {s.name: [] for s in services}
+    else:
+        partition_graph(overarching_graph_path, services)
+        bridges = analyze_bridges(overarching_graph_path, services)
     for svc in services:
         write_bridges_md(svc, bridges[svc.name])
         write_symbols_md(svc)
@@ -840,13 +913,14 @@ def run_map(
         print("Error: 'graphify' not found. Install with: pip install graphifyy", file=sys.stderr)
         return 1
 
-    services = detect_services(root, mono_cfg.marker_files, mono_cfg.extra_skip_dirs)
+    services, single = resolve_services(root, mono_cfg.marker_files, mono_cfg.extra_skip_dirs)
     if not services:
-        print(f"No services detected in {root}. Add code to subdirectories (or marker files like package.json/pyproject.toml).", file=sys.stderr)
+        print(f"No source code found in {root}. Run graphnav from a directory that contains code.", file=sys.stderr)
         return 1
 
+    shape = "whole repo (single project)" if single else f"{len(services)} service(s): {', '.join(s.name for s in services)}"
     if dry_run:
-        print(f"Detected {len(services)} service(s):")
+        print(f"Detected {shape}:")
         for svc in services:
             print(f"  {svc.name}  {svc.abs_path}")
         print("[dry-run] No graphify calls made.")
@@ -856,23 +930,34 @@ def run_map(
     env = _build_subprocess_env(root)
     overarching_path = _overarching_graph_path(root)
 
-    print(f"[graphnav] Building overarching graph across {len(services)} service(s): {', '.join(s.name for s in services)}", file=sys.stderr)
+    print(f"[graphnav] Building knowledge graph for {shape} ...", file=sys.stderr)
     rc = build_overarching_graph(root, graphify_path, backend, env=env)
     if rc != 0 or not os.path.exists(overarching_path):
-        print(f"Error: overarching graphify extraction failed (exit {rc}).", file=sys.stderr)
+        print(f"Error: graphify extraction failed (exit {rc}).", file=sys.stderr)
         print("  Ensure an API key is available (e.g. ANTHROPIC_API_KEY or ANTHROPIC_KEY in a .env file).", file=sys.stderr)
         return 1
 
-    bridges = _refresh(root, services, overarching_path)
+    try:
+        bridges = _refresh(root, services, overarching_path, single=single)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"Error: extracted graph could not be read ({type(exc).__name__}: {exc}).", file=sys.stderr)
+        print("  Re-run `graphnav map`; if it persists, delete graphify-out/ and try again.", file=sys.stderr)
+        return 1
     total_bridges = sum(len(rows) for rows in bridges.values())
 
-    print(f"\nDone. {len(services)} service(s) mapped, {total_bridges} cross-service connection(s) found.")
-    print(f"  Overarching graph    : {overarching_path}")
-    for svc in services:
-        to = ", ".join(svc.bridges_to) if svc.bridges_to else "none"
-        print(f"  {svc.name}/graphify-out/  (bridges -> {to})")
-    print(f"  Monorepo map         : {os.path.join(root, 'graphify-out', 'MONOREPO_MAP.md')}")
-    print(f"  Copilot instructions : {os.path.join(root, '.github', 'copilot-instructions.md')}")
+    print(f"\nSetup complete. Your AI coding agents are now configured for this repo.")
+    if single:
+        print(f"  Knowledge graph      : {overarching_path}")
+        print(f"  Symbol index         : {os.path.join(root, 'graphify-out', 'SYMBOLS.md')}")
+    else:
+        print(f"  {len(services)} service(s) mapped, {total_bridges} cross-service connection(s) found.")
+        print(f"  Overarching graph    : {overarching_path}")
+        for svc in services:
+            to = ", ".join(svc.bridges_to) if svc.bridges_to else "none"
+            print(f"  {svc.name}/graphify-out/  (bridges -> {to})")
+    print(f"  Agent instructions   : CLAUDE.md, AGENTS.md, .github/copilot-instructions.md")
+    print(f"\nNothing else to run. Open the repo in your AI coding tool and start working.")
+    print(f"(Optional: `graphnav watch` keeps the graph live as you edit.)")
     return 0
 
 
@@ -887,9 +972,9 @@ def run_watch(
         print("Error: 'graphify' not found. Install with: pip install graphifyy", file=sys.stderr)
         return 1
 
-    services = detect_services(root, mono_cfg.marker_files, mono_cfg.extra_skip_dirs)
+    services, single = resolve_services(root, mono_cfg.marker_files, mono_cfg.extra_skip_dirs)
     if not services:
-        print(f"No services detected in {root}.", file=sys.stderr)
+        print(f"No source code found in {root}.", file=sys.stderr)
         return 1
 
     backend = backend_override or mono_cfg.graphify_backend
@@ -897,13 +982,16 @@ def run_watch(
     overarching_path = _overarching_graph_path(root)
 
     if not os.path.exists(overarching_path):
-        print(f"[graphnav] Bootstrapping overarching graph for {len(services)} service(s) ...", file=sys.stderr)
+        print(f"[graphnav] Bootstrapping knowledge graph ...", file=sys.stderr)
         rc = build_overarching_graph(root, graphify_path, backend, env=env)
         if rc != 0 or not os.path.exists(overarching_path):
             print(f"Error: bootstrap extraction failed (exit {rc}).", file=sys.stderr)
             return 1
 
-    _refresh(root, services, overarching_path)
+    try:
+        _refresh(root, services, overarching_path, single=single)
+    except (OSError, json.JSONDecodeError) as exc:
+        _warn(f"could not read graph.json ({type(exc).__name__}) — will retry as it updates")
 
     def _start_watch() -> subprocess.Popen:
         return subprocess.Popen(
@@ -913,6 +1001,14 @@ def run_watch(
             env=env,
         )
 
+    def _sigterm(_signum, _frame):
+        raise KeyboardInterrupt
+
+    try:
+        signal.signal(signal.SIGTERM, _sigterm)
+    except (ValueError, OSError):
+        pass
+
     watch_proc = _start_watch()
     backoff = RestartBackoff()
     backoff.record_start(time.monotonic())
@@ -937,8 +1033,12 @@ def run_watch(
                     last_mtime = mtime
                     pending_mtime = None
                     ts = time.strftime("%H:%M:%S")
-                    print(f"[graphnav] {ts} graph updated — re-partitioning and re-analyzing bridges ...", file=sys.stderr)
-                    _refresh(root, services, overarching_path)
+                    print(f"[graphnav] {ts} graph updated — refreshing symbols and bridges ...", file=sys.stderr)
+                    try:
+                        _refresh(root, services, overarching_path, single=single)
+                    except (OSError, json.JSONDecodeError) as exc:
+                        _warn(f"could not read graph.json ({type(exc).__name__}) — will retry on next update")
+                        last_mtime = 0.0
                 else:
                     pending_mtime = mtime
             elif mtime != last_mtime:

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

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

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

@@ -25,4 +25,5 @@ tests/test_graph_nav.py
 tests/test_graph_query.py
 tests/test_mcp_server.py
 tests/test_multirepo.py
+tests/test_robustness.py
 tests/test_runner.py

graphnav-1.2.3/graphnav.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+graphnav = codex_graph.cli:entry

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

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphnav"
-version = "1.2.1"
+version = "1.2.3"
 description = "Knowledge-graph context injection for AI coding agents in monorepos"
 license = "MIT"
 requires-python = ">=3.11"
 dependencies = ["graphifyy>=0.8", "mcp>=1.2"]
 
 [project.scripts]
-graphnav = "codex_graph.cli:main"
+graphnav = "codex_graph.cli:entry"
 
 [project.optional-dependencies]
 dev = ["pytest>=8", "anthropic>=0.40"]

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

@@ -170,7 +170,7 @@ class TestAutoMap:
         assert exc.value.code == 0
         assert str(tmp_path) == called_with["root"]
 
-    def test_no_args_without_services_shows_help(self, tmp_path, monkeypatch, capsys):
+    def test_no_args_without_source_exits_with_guidance(self, tmp_path, monkeypatch, capsys):
         monkeypatch.setattr(sys, "argv", ["codex-graph"])
         monkeypatch.chdir(tmp_path)
         monkeypatch.setattr(sys.stdin, "isatty", lambda: True)
@@ -178,8 +178,27 @@ class TestAutoMap:
             from codex_graph.cli import main
             main()
         assert exc.value.code == 1
-        out = capsys.readouterr().out
-        assert "graphnav" in out
+        err = capsys.readouterr().err
+        assert "No source code" in err
+
+    def test_no_args_flat_repo_runs_map(self, tmp_path, monkeypatch, capsys):
+        (tmp_path / "app.py").write_text("def main():\n    return 1\n")
+        monkeypatch.setattr(sys, "argv", ["codex-graph"])
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setattr(sys.stdin, "isatty", lambda: True)
+
+        called = {}
+
+        def fake_run_map(root, mono_cfg, backend_override=None, dry_run=False):
+            called["root"] = root
+            return 0
+
+        monkeypatch.setattr("codex_graph.multirepo.run_map", fake_run_map)
+        with pytest.raises(SystemExit) as exc:
+            from codex_graph.cli import main
+            main()
+        assert exc.value.code == 0
+        assert called["root"] == str(tmp_path)
 
 
 class TestExistingPromptPathUnaffected:
@@ -275,7 +294,7 @@ class TestDoctorDispatch:
     def test_doctor_empty_root_fails(self, tmp_path, monkeypatch, capsys):
         from codex_graph import doctor
 
-        monkeypatch.setattr(doctor.shutil, "which", lambda _: None)
+        monkeypatch.setattr(doctor, "find_graphify", lambda: None)
         monkeypatch.setattr(sys, "argv", ["graphnav", "doctor", "--root", str(tmp_path)])
         with pytest.raises(SystemExit) as exc:
             from codex_graph.cli import main

{graphnav-1.2.1 → graphnav-1.2.3}/tests/test_doctor.py

@@ -27,7 +27,7 @@ def fresh_memo():
 
 @pytest.fixture
 def fake_graphify(monkeypatch):
-    monkeypatch.setattr(doctor.shutil, "which", lambda _: "/usr/bin/graphify")
+    monkeypatch.setattr(doctor, "find_graphify", lambda: "/usr/bin/graphify")
     monkeypatch.setattr(
         doctor.subprocess, "run",
         lambda *a, **k: subprocess.CompletedProcess(a, 0, stdout="graphify 0.9", stderr=""),
@@ -61,7 +61,7 @@ class TestDoctorAllPass:
 
 class TestDoctorGraphifyMissing:
     def test_missing_binary_fails(self, healthy_repo, monkeypatch, capsys):
-        monkeypatch.setattr(doctor.shutil, "which", lambda _: None)
+        monkeypatch.setattr(doctor, "find_graphify", lambda: None)
         rc = run_doctor(str(healthy_repo))
         out = capsys.readouterr().out
         assert rc == 1

{graphnav-1.2.1 → graphnav-1.2.3}/tests/test_multirepo.py

@@ -28,6 +28,7 @@ from codex_graph.multirepo import (
     build_playbook_text,
     detect_services,
     partition_graph,
+    resolve_services,
     run_extract,
     run_map,
     run_watch,
@@ -188,6 +189,27 @@ class TestDetectServices:
         assert result[0].graph_path == str(d / "graphify-out" / "graph.json")
         assert result[0].bridges_to == []
 
+    def test_resolve_falls_back_to_whole_repo_when_no_subdir_services(self, tmp_path):
+        (tmp_path / "app.py").write_text("def main():\n    return 1\n")
+        services, single = resolve_services(str(tmp_path), ["pyproject.toml"])
+        assert single is True
+        assert len(services) == 1
+        assert services[0].abs_path == str(tmp_path)
+        assert services[0].graph_path == str(tmp_path / "graphify-out" / "graph.json")
+
+    def test_resolve_prefers_subdir_services(self, tmp_path):
+        d = tmp_path / "svc-a"
+        d.mkdir()
+        (d / "pyproject.toml").touch()
+        services, single = resolve_services(str(tmp_path), ["pyproject.toml"])
+        assert single is False
+        assert [s.name for s in services] == ["svc-a"]
+
+    def test_resolve_empty_dir_returns_nothing(self, tmp_path):
+        services, single = resolve_services(str(tmp_path), ["pyproject.toml"])
+        assert services == []
+        assert single is False
+
     def test_services_returned_in_sorted_order(self, tmp_path):
         for name in ("zebra", "alpha", "middle"):
             d = tmp_path / name
@@ -1177,11 +1199,11 @@ class TestRunMap:
         monkeypatch.setattr("codex_graph.multirepo.shutil.which", lambda _: "/graphify")
         roots_seen = []
 
-        def fake_detect(root, markers, extra_skip_dirs=None):
+        def fake_resolve(root, markers, extra_skip_dirs=None):
             roots_seen.append(root)
-            return []
+            return [], False
 
-        monkeypatch.setattr("codex_graph.multirepo.detect_services", fake_detect)
+        monkeypatch.setattr("codex_graph.multirepo.resolve_services", fake_resolve)
         run_map(".", MonoConfig())
         assert os.path.isabs(roots_seen[0])
 

graphnav-1.2.3/tests/test_robustness.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import json
+import sys
+
+import pytest
+
+from codex_graph.config import load_config_report
+from codex_graph.graph_nav import GraphNav
+from codex_graph.multirepo import (
+    _load_env_file,
+    _parse_env_file,
+    build_context_pack_inline,
+    resolve_services,
+)
+from tests.conftest import write_graph
+
+
+class TestFlatRepoDetection:
+    def test_src_and_tests_dirs_without_markers_is_single_project(self, tmp_path):
+        (tmp_path / "src").mkdir()
+        (tmp_path / "src" / "main.py").write_text("def main():\n    pass\n")
+        (tmp_path / "tests").mkdir()
+        (tmp_path / "tests" / "test_main.py").write_text("def test_x():\n    pass\n")
+        services, single = resolve_services(str(tmp_path), ["pyproject.toml", "package.json"])
+        assert single is True
+        assert len(services) == 1
+        assert services[0].abs_path == str(tmp_path)
+
+    def test_root_marker_with_tests_dir_is_single_project(self, tmp_path):
+        (tmp_path / "pyproject.toml").touch()
+        (tmp_path / "app.py").write_text("x = 1\n")
+        (tmp_path / "tests").mkdir()
+        (tmp_path / "tests" / "test_app.py").write_text("y = 2\n")
+        services, single = resolve_services(str(tmp_path), ["pyproject.toml"])
+        assert single is True
+
+    def test_subdir_marker_still_monorepo(self, tmp_path):
+        for name in ("backend", "frontend"):
+            d = tmp_path / name
+            d.mkdir()
+            (d / "package.json").touch()
+        services, single = resolve_services(str(tmp_path), ["package.json"])
+        assert single is False
+        assert [s.name for s in services] == ["backend", "frontend"]
+
+    def test_one_marker_subdir_pulls_in_source_only_dirs(self, tmp_path):
+        backend = tmp_path / "backend"
+        backend.mkdir()
+        (backend / "pyproject.toml").touch()
+        shared = tmp_path / "shared"
+        shared.mkdir()
+        (shared / "util.py").write_text("z = 3\n")
+        services, single = resolve_services(str(tmp_path), ["pyproject.toml"])
+        assert single is False
+        assert {s.name for s in services} == {"backend", "shared"}
+
+
+class TestConfigRobustness:
+    def test_malformed_toml_falls_back_to_defaults(self, tmp_path, monkeypatch):
+        (tmp_path / "config.toml").write_text("[query\ntop_k = 3\n")
+        monkeypatch.chdir(tmp_path)
+        cfg, source, warnings = load_config_report()
+        assert cfg.query.top_k == 5
+        assert any("could not parse" in w for w in warnings)
+
+    def test_foreign_config_toml_ignored(self, tmp_path, monkeypatch):
+        (tmp_path / "config.toml").write_text('[params]\ntitle = "My Hugo Site"\nbaseURL = "x"\n')
+        monkeypatch.chdir(tmp_path)
+        cfg, source, warnings = load_config_report()
+        assert source is None
+        assert warnings == []
+
+    def test_wrong_typed_value_uses_default(self, tmp_path, monkeypatch):
+        (tmp_path / "config.toml").write_text('[query]\ntop_k = "five"\n')
+        monkeypatch.chdir(tmp_path)
+        cfg, source, warnings = load_config_report()
+        assert cfg.query.top_k == 5
+        assert any("invalid value" in w for w in warnings)
+
+    def test_wrong_typed_list_uses_default(self, tmp_path, monkeypatch):
+        (tmp_path / "config.toml").write_text('[mono]\nmarker_files = "package.json"\n')
+        monkeypatch.chdir(tmp_path)
+        cfg, source, warnings = load_config_report()
+        assert "pyproject.toml" in cfg.mono.marker_files
+        assert any("list of strings" in w for w in warnings)
+
+    def test_explicit_path_with_no_known_sections_still_loads(self, tmp_path):
+        p = tmp_path / "custom.toml"
+        p.write_text("")
+        cfg, source, warnings = load_config_report(str(p))
+        assert source == str(p)
+
+
+class TestNeighborsExactMatch:
+    def test_exact_label_beats_superstring(self):
+        graph = {
+            "nodes": [
+                {"id": "test_main", "label": "test_main", "source_file": "tests/test_app.py",
+                 "file_type": "code", "source_location": "L1"},
+                {"id": "main", "label": "main", "source_file": "app.py",
+                 "file_type": "code", "source_location": "L5"},
+            ],
+            "links": [],
+        }
+        nav = GraphNav("unused", graph=graph)
+        r = nav.neighbors("main")
+        assert r["symbol"] == "main"
+        assert r["defined_at"] == "app.py:L5"
+
+
+class TestGraphNavEdgesKey:
+    def test_edges_key_fallback(self, tmp_path):
+        graph = {
+            "nodes": [
+                {"id": "a", "label": "alpha_func", "source_file": "a.py",
+                 "file_type": "code", "source_location": "L1"},
+                {"id": "b", "label": "beta_func", "source_file": "b.py",
+                 "file_type": "code", "source_location": "L2"},
+            ],
+            "edges": [{"source": "a", "target": "b", "relation": "calls"}],
+        }
+        nav = GraphNav("unused", graph=graph)
+        r = nav.neighbors("alpha_func")
+        assert r["callees"]
+        assert "beta_func" in r["callees"][0]
+
+
+class TestEnvFileParsing:
+    def test_bom_stripped(self, tmp_path):
+        p = tmp_path / ".env"
+        p.write_bytes("ANTHROPIC_API_KEY=sk-bom\n".encode("utf-8"))
+        env = _parse_env_file(str(p))
+        assert env.get("ANTHROPIC_API_KEY") == "sk-bom"
+
+    def test_openai_key_alias(self, tmp_path, monkeypatch):
+        (tmp_path / ".env").write_text("OPENAI_KEY=sk-oai\n")
+        monkeypatch.chdir(tmp_path)
+        env = _load_env_file(str(tmp_path))
+        assert env.get("OPENAI_API_KEY") == "sk-oai"
+
+
+class TestDoctorFlatRepo:
+    def test_flat_repo_services_check_passes(self, tmp_path, monkeypatch, capsys):
+        from codex_graph import doctor
+
+        (tmp_path / "app.py").write_text("def main():\n    pass\n")
+        write_graph(
+            tmp_path / "graphify-out" / "graph.json",
+            [{"id": "m", "label": "main", "source_file": "app.py",
+              "file_type": "code", "source_location": "L1", "community": 0}],
+            [],
+        )
+        (tmp_path / "graphify-out" / ".graphnav-meta.json").write_text(
+            json.dumps({"built_at": "x", "git_sha": None})
+        )
+        monkeypatch.setattr(doctor, "find_graphify", lambda: "/usr/bin/graphify")
+        monkeypatch.setattr(
+            doctor.subprocess, "run",
+            lambda *a, **k: __import__("subprocess").CompletedProcess(a, 0, stdout="graphify 0.9", stderr=""),
+        )
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test")
+        rc = doctor.run_doctor(str(tmp_path))
+        out = capsys.readouterr().out
+        assert rc == 0
+        assert "single project" in out
+
+
+class TestCorruptGraphCli:
+    def test_find_with_corrupt_graph_exits_2(self, tmp_path, monkeypatch, capsys):
+        (tmp_path / "graphify-out").mkdir()
+        (tmp_path / "graphify-out" / "graph.json").write_text("{not json")
+        monkeypatch.setattr(
+            sys, "argv", ["graphnav", "find", "anything", "--root", str(tmp_path)]
+        )
+        from codex_graph.cli import main
+
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 2
+        err = capsys.readouterr().err
+        assert "graphnav map" in err
+
+
+class TestInlinePackTruncation:
+    def test_truncation_balances_code_fences(self, tmp_path):
+        nodes = []
+        for i in range(40):
+            name = f"mod_{i}"
+            src = tmp_path / f"{name}.py"
+            src.write_text("\n".join(f"def fn_{j}():\n    pass" for j in range(30)))
+            nodes.append({
+                "id": name, "label": f"search target term {i}", "source_file": f"{name}.py",
+                "file_type": "code", "source_location": "L1", "community": 0,
+            })
+        write_graph(tmp_path / "graphify-out" / "graph.json", nodes, [])
+        pack = build_context_pack_inline(
+            str(tmp_path), "search target term", top_files=8, budget_tokens=100
+        )
+        assert "_(truncated to budget)_" in pack
+        assert pack.count("```") % 2 == 0

graphnav-1.2.1/graphnav.egg-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-graphnav = codex_graph.cli:main