graphnav 1.2.0__tar.gz → 1.2.2__tar.gz

{graphnav-1.2.0/graphnav.egg-info → graphnav-1.2.2}/PKG-INFO

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

{graphnav-1.2.0 → graphnav-1.2.2}/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
 ```
 
@@ -360,6 +375,12 @@ The generated `CLAUDE.md`, `AGENTS.md`, and `.github/copilot-instructions.md` ca
 
 ---
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a full version history.
+
+---
+
 ## License
 
 [MIT](LICENSE) © 2026 Amogh Rao

{graphnav-1.2.0 → graphnav-1.2.2}/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)
 
@@ -216,16 +219,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 +250,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()

{graphnav-1.2.0 → graphnav-1.2.2}/codex_graph/doctor.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import json
 import os
-import shutil
 import subprocess
 from dataclasses import dataclass
 
@@ -13,6 +12,7 @@ from codex_graph.multirepo import (
     _load_env_file,
     _overarching_graph_path,
     detect_services,
+    find_graphify,
     staleness_note,
 )
 
@@ -35,9 +35,9 @@ class CheckResult:
 
 
 def _check_graphify_binary() -> CheckResult:
-    path = shutil.which("graphify")
+    path = find_graphify()
     if path is None:
-        return CheckResult("fail", "graphify binary", "not found on PATH — install with: pip install graphifyy")
+        return CheckResult("fail", "graphify binary", "not found — install with: pip install graphifyy")
     detail = path
     try:
         out = subprocess.run([path, "--version"], capture_output=True, text=True, timeout=5)

{graphnav-1.2.0 → graphnav-1.2.2}/codex_graph/multirepo.py

@@ -13,6 +13,52 @@ from dataclasses import dataclass, field
 from codex_graph.config import MonoConfig, QueryConfig
 
 
+def find_graphify() -> str | None:
+    path = shutil.which("graphify")
+    if path:
+        return path
+    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 resolve_services(
+    root: str,
+    marker_files: list[str],
+    extra_skip_dirs: list[str] | None = None,
+) -> tuple[list[ServiceInfo], bool]:
+    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)
 
@@ -806,9 +852,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)
@@ -825,18 +875,19 @@ def run_map(
     dry_run: bool = False,
 ) -> int:
     root = os.path.abspath(root)
-    graphify_path = shutil.which("graphify")
+    graphify_path = find_graphify()
     if graphify_path is None:
-        print("Error: 'graphify' not found on PATH. Install with: pip install graphifyy", file=sys.stderr)
+        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.")
@@ -846,23 +897,29 @@ 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)
+    bridges = _refresh(root, services, overarching_path, single=single)
     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
 
 
@@ -872,14 +929,14 @@ def run_watch(
     backend_override: str | None = None,
 ) -> int:
     root = os.path.abspath(root)
-    graphify_path = shutil.which("graphify")
+    graphify_path = find_graphify()
     if graphify_path is None:
-        print("Error: 'graphify' not found on PATH. Install with: pip install graphifyy", file=sys.stderr)
+        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
@@ -887,13 +944,13 @@ 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)
+    _refresh(root, services, overarching_path, single=single)
 
     def _start_watch() -> subprocess.Popen:
         return subprocess.Popen(
@@ -927,8 +984,8 @@ 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)
+                    _refresh(root, services, overarching_path, single=single)
                 else:
                     pending_mtime = mtime
             elif mtime != last_mtime:

{graphnav-1.2.0 → graphnav-1.2.2/graphnav.egg-info}/PKG-INFO

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

{graphnav-1.2.0 → graphnav-1.2.2}/pyproject.toml

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

{graphnav-1.2.0 → graphnav-1.2.2}/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.0 → graphnav-1.2.2}/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.0 → graphnav-1.2.2}/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
@@ -1182,6 +1204,7 @@ class TestRunMap:
             return []
 
         monkeypatch.setattr("codex_graph.multirepo.detect_services", fake_detect)
+        monkeypatch.setattr("codex_graph.multirepo._has_source_files", lambda *a, **k: False)
         run_map(".", MonoConfig())
         assert os.path.isabs(roots_seen[0])