java-codebase-rag 0.6.7__py3-none-any.whl → 0.8.0__py3-none-any.whl

java_codebase_rag/cli.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-# Heavy imports (`server`, `pr_analysis`, `path_filtering.LayeredIgnore`) stay lazy
-# inside handlers so `java-codebase-rag --help` stays fast.
+# Heavy imports (`server`, `pr_analysis`, `path_filtering.LayeredIgnore`,
+# `build_ast_graph`) stay lazy inside handlers so `java-codebase-rag --help` stays fast.
 
 import argparse
 import asyncio
@@ -15,15 +15,25 @@ from pathlib import Path
 from typing import Any, Callable
 
 from java_codebase_rag.config import (
+    OPERATOR_OWNED_INDEX_FILES,
     ResolvedOperatorConfig,
     describe_path_sizes,
     emit_legacy_env_hints_if_present,
     emit_legacy_yaml_hint_if_needed,
     index_dir_has_existing_artifacts,
     resolve_operator_config,
+    write_config_source_pointer,
 )
 from java_codebase_rag._fdlimit import raise_fd_limit
-from java_codebase_rag.pipeline import clip, run_build_ast_graph, run_cocoindex_drop, run_cocoindex_update, run_incremental_graph
+from java_codebase_rag.pipeline import (
+    clip,
+    is_cocoindex_preflight_blocker,
+    is_graph_preflight_blocker,
+    run_build_ast_graph,
+    run_cocoindex_drop,
+    run_cocoindex_update,
+    run_incremental_graph,
+)
 from java_ontology import VALID_UNRESOLVED_CALL_REASONS
 
 LADYBUG_INCREMENTAL_TRACKING_ISSUE_URL = "https://github.com/HumanBean17/java-codebase-rag/issues/73"
@@ -61,6 +71,12 @@ def _reprocess_drift_graph_only_line(index_dir: Path) -> str:
     )
 
 
+_VECTORS_SKIPPED_GRAPH_ONLY = (
+    "java-codebase-rag: vectors skipped — vector stack not installed on this platform "
+    "(graph-only mode). The graph is built/refreshed; semantic search is unavailable."
+)
+
+
 def _reprocess_exit_code(payload: dict[str, Any]) -> int:
     if payload.get("success"):
         return 0
@@ -70,16 +86,17 @@ def _reprocess_exit_code(payload: dict[str, Any]) -> int:
     return 1
 
 
-# Preflight detection must stay aligned with stub CompletedProcess shapes in
-# java_codebase_rag/pipeline.py (missing cocoindex / flow / build_ast_graph.py).
+# Preflight detection delegates to pipeline.is_cocoindex_preflight_blocker /
+# is_graph_preflight_blocker, which are co-located with the stub CompletedProcess shapes
+# they must match (missing cocoindex / flow / build_ast_graph.py).
 def _is_cocoindex_preflight_blocker(coco: Any) -> bool:
     """True when ``run_cocoindex_update`` returned without spawning cocoindex."""
-    return bool(coco.returncode in (126, 127) and len(getattr(coco, "args", ()) or ()) <= 1)
+    return is_cocoindex_preflight_blocker(coco)
 
 
 def _is_graph_preflight_blocker(g: Any) -> bool:
     """True when ``run_build_ast_graph`` returned without spawning the builder."""
-    return bool(g.returncode in (126, 127) and len(getattr(g, "args", ()) or ()) <= 1)
+    return is_graph_preflight_blocker(g)
 
 
 def _emit_reprocess_selective_tty(*, mode: str) -> None:
@@ -126,6 +143,21 @@ def _pipeline_footer(subcommand: str, started: float, exit_code: int) -> None:
     )
 
 
+# Subcommands that build/refresh an index and therefore should record which YAML
+# was used (so a later discovery run from a sibling/cwd can relocate it).
+_CONFIG_SOURCE_RECORDING_SUBCOMMANDS = frozenset({"init", "increment", "reprocess"})
+
+
+def _maybe_record_config_source(
+    subcommand: str, cfg: ResolvedOperatorConfig, code: int
+) -> None:
+    """On a successful index build, remember the YAML path inside the index dir."""
+    if code == 0 and subcommand in _CONFIG_SOURCE_RECORDING_SUBCOMMANDS:
+        write_config_source_pointer(
+            index_dir=cfg.index_dir, yaml_config_path=cfg.yaml_config_path
+        )
+
+
 def _run_with_pipeline_progress(
     subcommand: str,
     cfg: ResolvedOperatorConfig,
@@ -143,7 +175,9 @@ def _run_with_pipeline_progress(
     raw-relays subprocess output).
     """
     if quiet or verbose:
-        return int(work(None))
+        code = int(work(None))
+        _maybe_record_config_source(subcommand, cfg, code)
+        return code
     from java_codebase_rag.progress import build_index_progress_context
 
     # PR-3 owns all three tasks in order: Vectors → Optimize → Graph. The vectors
@@ -183,6 +217,7 @@ def _run_with_pipeline_progress(
     finally:
         renderer.stop()
         _pipeline_footer(subcommand, t0, code)
+        _maybe_record_config_source(subcommand, cfg, code)
 
 
 class PipelineProgress:
@@ -321,7 +356,11 @@ def _cmd_init(args: argparse.Namespace) -> int:
             on_progress=progress.on_progress if progress is not None else None,
             on_progress_console=progress.console if progress is not None else None,
         )
-        if coco.returncode != 0:
+        # Graph-only install (cocoindex absent, e.g. macOS Intel): skip the vectors phase
+        # and proceed to the graph build rather than failing — the graph layer is the
+        # supported surface there. A genuine non-zero cocoindex exit still fails.
+        vectors_skipped = _is_cocoindex_preflight_blocker(coco)
+        if coco.returncode != 0 and not vectors_skipped:
             _emit(
                 {
                     "success": False,
@@ -332,6 +371,8 @@ def _cmd_init(args: argparse.Namespace) -> int:
                 }
             )
             return 1
+        if vectors_skipped:
+            print(_VECTORS_SKIPPED_GRAPH_ONLY, file=sys.stderr, flush=True)
         if not args.quiet:
             print(file=sys.stderr, flush=True)
         g = run_build_ast_graph(
@@ -354,7 +395,16 @@ def _cmd_init(args: argparse.Namespace) -> int:
                 }
             )
             return 1
-        _emit({"success": True, "message": "init completed"})
+        _emit(
+            {
+                "success": True,
+                "message": (
+                    "init completed (graph-only; vectors skipped — vector stack not installed)"
+                    if vectors_skipped
+                    else "init completed"
+                ),
+            }
+        )
         return 0
 
     return _run_with_pipeline_progress(
@@ -383,7 +433,8 @@ def _cmd_increment(args: argparse.Namespace) -> int:
             on_progress=progress.on_progress if progress is not None else None,
             on_progress_console=progress.console if progress is not None else None,
         )
-        if coco.returncode != 0:
+        vectors_skipped = _is_cocoindex_preflight_blocker(coco)
+        if coco.returncode != 0 and not vectors_skipped:
             _emit(
                 {
                     "success": False,
@@ -394,9 +445,19 @@ def _cmd_increment(args: argparse.Namespace) -> int:
                 }
             )
             return 1
+        if vectors_skipped:
+            print(_VECTORS_SKIPPED_GRAPH_ONLY, file=sys.stderr, flush=True)
 
         # If --vectors-only is set, skip graph update
         if vectors_only:
+            if vectors_skipped:
+                _emit(
+                    {
+                        "success": True,
+                        "message": "increment skipped: vector stack not installed (graph-only mode)",
+                    }
+                )
+                return 0
             _emit({"success": True, "message": "increment completed (Lance only; graph may be stale — see stderr)"})
             return 0
 
@@ -439,7 +500,16 @@ def _cmd_increment(args: argparse.Namespace) -> int:
             )
             return 1
 
-        _emit({"success": True, "message": "increment completed (Lance + graph updated)"})
+        _emit(
+            {
+                "success": True,
+                "message": (
+                    "increment completed (graph only; vectors skipped — vector stack not installed)"
+                    if vectors_skipped
+                    else "increment completed (Lance + graph updated)"
+                ),
+            }
+        )
         return 0
 
     return _run_with_pipeline_progress(
@@ -563,6 +633,7 @@ def _cmd_install(args: argparse.Namespace) -> int:
         agents=args.agent,  # list of str (may be empty)
         scope=args.scope,
         model=args.model,
+        surface=args.surface,
         source_root=None,  # None means cwd; installer confirms interactively
         quiet=bool(args.quiet),
         verbose=bool(args.verbose),
@@ -605,14 +676,25 @@ def _cmd_erase(args: argparse.Namespace) -> int:
     cfg = _resolved_from_ns(args)
     _startup_hints(cfg)
     cfg.apply_to_os_environ()
-    graph_hashes_path = cfg.ladybug_path.parent / ".graph_hashes.json"
-    to_describe: list[Path] = [cfg.ladybug_path, cfg.cocoindex_db, graph_hashes_path]
+    # Lazy import: build_ast_graph transitively pulls numpy/ladybug/pyarrow/
+    # tree_sitter (~54ms), and these filenames are only needed on the erase path.
+    # Keeping it out of the top-level import lets `java-codebase-rag --help` (and
+    # every other command) stay fast -- see the lazy-import invariant atop this file.
+    from build_ast_graph import BUILDER_OWNED_INDEX_FILES
+    builder_paths = [cfg.ladybug_path.parent / name for name in BUILDER_OWNED_INDEX_FILES]
+    operator_paths = [cfg.index_dir / name for name in OPERATOR_OWNED_INDEX_FILES]
+    to_describe: list[Path] = [
+        cfg.ladybug_path,
+        cfg.cocoindex_db,
+        *builder_paths,
+        *operator_paths,
+    ]
     if cfg.index_dir.is_dir():
         try:
             import lancedb
 
             db = lancedb.connect(str(cfg.index_dir.resolve()))
-            for name in db.table_names():
+            for name in db.list_tables():
                 to_describe.append(cfg.index_dir / name)
         except Exception:
             pass
@@ -627,7 +709,17 @@ def _cmd_erase(args: argparse.Namespace) -> int:
                 file=sys.stderr,
             )
             return 2
-        ans = input("Delete these paths? [y/N]: ").strip().lower()
+        try:
+            ans = input("Delete these paths? [y/N]: ").strip().lower()
+        except EOFError:
+            # Non-interactive stdin that nonetheless reported isatty() == True
+            # (the Windows NUL device is a character device, so isatty() lies).
+            # Treat it as a refusal instead of crashing with an EOF traceback.
+            print(
+                "java-codebase-rag erase: non-interactive stdin; pass --yes to confirm.",
+                file=sys.stderr,
+            )
+            return 2
         if ans not in ("y", "yes"):
             print("Aborted.", file=sys.stderr)
             return 2
@@ -643,21 +735,29 @@ def _cmd_erase(args: argparse.Namespace) -> int:
             )
         elif drop.returncode != 0:
             print(clip(drop.stderr, 4000), file=sys.stderr)
-        # Remove the LadybugDB graph, the cocoindex state store, and the graph
-        # builder's content-hash store. Each is removed by type (see _rm_any):
-        # code_graph.lbug is a file here but may be a dir under kuzu, while
-        # cocoindex.db is a directory — a type-blind delete silently no-oped on
-        # one or the other, and .graph_hashes.json was never targeted at all
-        # (issue #346).
+        # Remove the LadybugDB graph, the cocoindex state store, and every
+        # builder-owned bookkeeping file next to code_graph.lbug (the content-hash
+        # store, its atomic-write temp, and the incremental crash marker). Each is
+        # removed by type (see _rm_any): code_graph.lbug is a file here but may be
+        # a dir under kuzu, while cocoindex.db is a directory — a type-blind delete
+        # silently no-oped on one or the other, and the builder files were never
+        # targeted at all (issues #346 / #349 / #350). The list comes from
+        # build_ast_graph.BUILDER_OWNED_INDEX_FILES so erase and the builder cannot drift.
         _rm_any(cfg.ladybug_path)
         _rm_any(cfg.cocoindex_db)
-        _rm_any(graph_hashes_path)
+        for builder_path in builder_paths:
+            _rm_any(builder_path)
+        # Operator-owned index files (the config_source pointer recording which
+        # YAML built this index) — owned by the CLI/installer, not the graph
+        # builder, so removed here rather than via BUILDER_OWNED_INDEX_FILES.
+        for operator_path in operator_paths:
+            _rm_any(operator_path)
         if cfg.index_dir.is_dir():
             try:
                 import lancedb
 
                 db = lancedb.connect(str(cfg.index_dir.resolve()))
-                for name in list(db.table_names()):
+                for name in list(db.list_tables()):
                     try:
                         db.drop_table(name)
                     except Exception as exc:
@@ -865,6 +965,17 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Embedding model path or 'auto' (default: auto).",
     )
+    install.add_argument(
+        "--surface",
+        choices=["mcp", "cli"],
+        default=None,
+        help=(
+            "Agent surface to install: 'mcp' (stdio MCP server + explore-codebase "
+            "skill + explorer-rag-enhanced subagent) or 'cli' (jrag console-script "
+            "skill + explorer-rag-cli subagent, no MCP entry). Omit to choose "
+            "interactively; non-interactive mode defaults to 'mcp'."
+        ),
+    )
     _add_verbosity_flags(install)
     install.set_defaults(handler=_cmd_install)
 

java_codebase_rag/config.py

@@ -18,6 +18,18 @@ SettingSource = Literal["cli", "env", "yaml", "default"]
 YAML_CONFIG_FILENAMES = (".java-codebase-rag.yml", ".java-codebase-rag.yaml")
 LEGACY_YAML_FILENAMES = (".lancedb-mcp.yml", ".lancedb-mcp.yaml")
 
+# Pointer file written into the index dir at index time so discovery can locate
+# a YAML that does not sit beside the index-dir anchor — e.g. a config living in
+# a sibling ``project-context/`` dir when the agent's cwd is inside a
+# microservice (a descendant of the index anchor, a sibling of the config).
+# Contains one line: the absolute path of the YAML used to build the index. A
+# direct YAML at the anchor always wins; the pointer only fires when the anchor
+# has no YAML beside it (see ``_effective_config_dir``).
+CONFIG_SOURCE_FILENAME = "config_source"
+# Operator-owned files inside the index dir that ``erase`` removes. Kept separate
+# from ``build_ast_graph.BUILDER_OWNED_INDEX_FILES`` (builder-owned artifacts).
+OPERATOR_OWNED_INDEX_FILES = (CONFIG_SOURCE_FILENAME,)
+
 ENV_INDEX_DIR = "JAVA_CODEBASE_RAG_INDEX_DIR"
 # Public operator contract is six names: INDEX_DIR, DEBUG_CONTEXT, RUN_HEAVY, SBERT_MODEL, SBERT_DEVICE, HINTS_ENABLED.
 # SOURCE_ROOT is still required for MCP / subprocess Java tree resolution (see mcp.json.example); it is not folded into the headline "5".
@@ -202,20 +214,27 @@ def discover_project_root(start: Path) -> Path | None:
     First match wins (closest to start). Config file takes priority over index
     directory at the same level. Stops at $HOME inclusive — checks $HOME itself
     but does not walk past it. Returns None if no marker found.
+
+    A bare ``.java-codebase-rag/`` index directory at ``$HOME`` is intentionally
+    NOT treated as an anchor (issue #357): a stray home-level index (e.g. an
+    accidental ``init`` run from home) would otherwise hijack resolution for any
+    command run from a ``$HOME`` subdir without its own marker, silently reading
+    and writing the home-level index. A config file at ``$HOME`` still anchors.
     """
     start = start.resolve()
     home = Path.home().resolve()
 
     current = start
     while True:
-        # Config file is the primary anchor
+        # Config file is the primary anchor (valid at every level, including $HOME).
         if find_yaml_config_file(current) is not None:
             return current
-        # Index directory is the secondary anchor (supports indexes without config)
-        if _has_index_dir(current):
+        # Index directory is the secondary anchor (supports indexes without config),
+        # but NOT at $HOME — see the docstring for the cross-project hijack rationale.
+        if current != home and _has_index_dir(current):
             return current
 
-        # Stop if we've reached home (check home itself, but don't walk past it)
+        # Stop if we've reached home (config-file check above already handled home)
         if current == home:
             return None
 
@@ -227,6 +246,61 @@ def discover_project_root(start: Path) -> Path | None:
         current = parent
 
 
+_stale_pointer_seen: set[str] = set()
+
+
+def _config_dir_from_pointer(anchor: Path) -> Path | None:
+    """Return the YAML config dir recorded in the index dir's ``config_source`` pointer.
+
+    Reads ``<anchor>/.java-codebase-rag/config_source`` (one absolute path). If it
+    names an existing ``.java-codebase-rag.yml`` / ``.yaml``, returns that file's
+    parent directory; otherwise (missing/blank/stale) returns ``None``. Used only
+    when the anchor has no direct YAML — see :func:`_effective_config_dir`.
+    """
+    pointer = anchor / ".java-codebase-rag" / CONFIG_SOURCE_FILENAME
+    if not pointer.is_file():
+        return None
+    try:
+        raw = pointer.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if not raw:
+        return None
+    target = Path(raw).expanduser()
+    if not target.is_absolute():
+        # Relative to the anchor (the index-dir parent), not the pointer file.
+        target = (anchor / target).resolve()
+    if not target.is_file() or target.name not in YAML_CONFIG_FILENAMES:
+        key = str(pointer.resolve())
+        if key not in _stale_pointer_seen:
+            _stale_pointer_seen.add(key)
+            print(
+                "java-codebase-rag: ignoring stale index pointer "
+                f"{pointer} -> {raw} (target missing or not a config file).",
+                file=sys.stderr,
+            )
+        return None
+    return target.parent
+
+
+def _effective_config_dir(config_dir: Path) -> Path:
+    """Resolve the directory YAML config fields are relative to.
+
+    A direct ``.java-codebase-rag.yml`` / ``.yaml`` in ``config_dir`` always wins.
+    Otherwise, if ``config_dir`` hosts the ``.java-codebase-rag/`` index dir and
+    that index remembers its config via a ``config_source`` pointer, follow it to
+    the YAML's directory. This lets a config in a sibling dir (e.g.
+    ``project-context/`` beside the Java tree) be found when discovery anchors on
+    the index dir from inside a microservice — without an env var or flag, and
+    with YAML-relative fields (``index_dir``, ``source_root``, ``embedding.model``)
+    resolving against the YAML's home rather than the index anchor. Falls back to
+    ``config_dir`` unchanged when neither applies.
+    """
+    if find_yaml_config_file(config_dir) is not None:
+        return config_dir
+    return _config_dir_from_pointer(config_dir) or config_dir
+
+
 def load_yaml_mapping(source_root: Path) -> dict[str, Any]:
     path = find_yaml_config_file(source_root)
     if path is None:
@@ -237,7 +311,17 @@ def load_yaml_mapping(source_root: Path) -> dict[str, Any]:
         return {}
     try:
         data = yaml.safe_load(path.read_text(encoding="utf-8"))
-    except Exception:
+    except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+        # Best-effort loader: a missing/unreadable/malformed config must NOT abort
+        # startup — return {} and proceed with defaults. Narrowing this to
+        # ``yaml.YAMLError`` alone let OSError (chmod 000, stat/read TOCTOU) and
+        # UnicodeDecodeError (non-UTF-8 config) propagate to the caller; the broader
+        # tuple restores the graceful-degradation contract while still surfacing the
+        # problem on stderr.
+        print(
+            f"java-codebase-rag: could not load config {path}: {exc}; ignoring config.",
+            file=sys.stderr,
+        )
         return {}
     return data if isinstance(data, dict) else {}
 
@@ -255,6 +339,10 @@ class ResolvedOperatorConfig:
     embedding_model_source: SettingSource
     embedding_device_source: SettingSource
     hints_enabled_source: SettingSource
+    # Absolute path of the YAML actually loaded (None when built-in defaults were
+    # used with no config file). Recorded into the index dir at index time so a
+    # later discovery run from a sibling/cwd can relocate this config.
+    yaml_config_path: Path | None = None
 
     def apply_to_os_environ(self) -> None:
         """Make downstream modules (server, ladybug_queries, flows) see a consistent environment.
@@ -394,21 +482,26 @@ def resolve_operator_config(
     # Phase 1: Find the config file directory
     if source_root is not None:
         # CLI flag provided: use it as both config_dir and effective source_root
-        # (skip YAML source_root check - CLI wins)
+        # (skip YAML source_root check - CLI wins). ``_effective_config_dir`` may
+        # rebase config_dir to a YAML reached via the index-dir pointer; root is
+        # untouched (explicit source_root wins).
         root = source_root.expanduser().resolve()
-        config_dir = root
+        config_dir = _effective_config_dir(root)
         yaml_dict = load_yaml_mapping(config_dir)
     else:
         # Check env var first
         env_raw = os.environ.get(ENV_SOURCE_ROOT, "").strip()
         if env_raw:
             root = Path(env_raw).expanduser().resolve()
-            config_dir = root
+            config_dir = _effective_config_dir(root)
             yaml_dict = load_yaml_mapping(config_dir)
         else:
             # Walk up to find config dir
             discovered = discover_project_root(Path.cwd())
             config_dir = discovered if discovered is not None else Path.cwd().resolve()
+            # Follow an index-dir pointer to the real config dir when the anchor
+            # has no YAML beside it (e.g. config in a sibling dir).
+            config_dir = _effective_config_dir(config_dir)
             # Load YAML from config dir
             yaml_dict = load_yaml_mapping(config_dir)
 
@@ -462,9 +555,35 @@ def resolve_operator_config(
         embedding_model_source=model_src,
         embedding_device_source=device_src,
         hints_enabled_source=hints_src,
+        yaml_config_path=find_yaml_config_file(config_dir),
     )
 
 
+def write_config_source_pointer(
+    *, index_dir: Path, yaml_config_path: Path | None
+) -> None:
+    """Record the YAML config path inside the index dir (best-effort).
+
+    Writes ``<index_dir>/config_source`` with the YAML's absolute path so a later
+    discovery run that anchors on the index dir (but has no YAML beside it) can
+    relocate the config via :func:`_effective_config_dir`. No-op when
+    ``yaml_config_path`` is None (pure-default build — nothing to remember). Never
+    raises: the pointer is an optimization, not a correctness requirement — a
+    missing/unreadable pointer just falls back to built-in defaults.
+    """
+    if yaml_config_path is None:
+        return
+    try:
+        index_dir.mkdir(parents=True, exist_ok=True)
+        content = str(yaml_config_path.resolve()) + "\n"
+        target = index_dir / CONFIG_SOURCE_FILENAME
+        tmp = index_dir / (CONFIG_SOURCE_FILENAME + ".tmp")
+        tmp.write_text(content, encoding="utf-8")
+        os.replace(tmp, target)
+    except OSError:
+        pass
+
+
 def index_dir_has_existing_artifacts(index_dir: Path) -> tuple[bool, list[str]]:
     """True if graph dir or any Lance table already exists under index_dir."""
     paths: list[str] = []
@@ -476,7 +595,7 @@ def index_dir_has_existing_artifacts(index_dir: Path) -> tuple[bool, list[str]]:
             import lancedb
 
             db = lancedb.connect(str(index_dir.resolve()))
-            for name in db.table_names():
+            for name in db.list_tables():
                 paths.append(str((index_dir / name).resolve()) + " (Lance table)")
         except Exception:
             pass