java-codebase-rag 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

java_codebase_rag/cli.py

@@ -131,15 +131,41 @@ def _run_with_pipeline_progress(
     cfg: ResolvedOperatorConfig,
     *,
     quiet: bool,
-    work: Callable[[], int],
+    verbose: bool = False,
+    work: Callable[["PipelineProgress | None"], int],
 ) -> int:
-    if quiet:
-        return int(work())
+    """Run ``work`` under the unified progress renderer (default TTY mode only).
+
+    ``work`` receives a :class:`PipelineProgress` whose ``on_progress`` callback
+    should be forwarded to the graph/vectors pipeline helpers so their
+    ``JCIRAG_PROGRESS`` events feed the renderer. In ``--quiet`` or ``--verbose``
+    mode the context is ``None`` (no Live region: quiet is silent, verbose
+    raw-relays subprocess output).
+    """
+    if quiet or verbose:
+        return int(work(None))
+    from java_codebase_rag.progress import build_index_progress_context
+
+    # PR-3 owns all three tasks in order: Vectors → Optimize → Graph. The vectors
+    # task is fed by the cocoindex child's per-file ticks + approximate total
+    # (subprocess transport, parsed by ProgressRelay); the optimize task is fed
+    # in-process by lance_optimize; the graph task is fed by the build_ast_graph
+    # child (subprocess transport). A task only becomes visible/running once its
+    # first event arrives.
+    renderer, on_progress, console = build_index_progress_context()
+    progress = PipelineProgress(renderer=renderer)
+    progress.on_progress = on_progress
+    progress.console = console
+
     _pipeline_header(subcommand, cfg)
     t0 = time.perf_counter()
     code = 0
+    # start() always flips _started (the non-TTY fallback is a no-op for Live but
+    # still needs the flag so apply() routes to the concise-line printer). The
+    # TTY Live region is entered inside start() only when the console is a TTY.
+    renderer.start()
     try:
-        code = int(work())
+        code = int(work(progress))
         return code
     except BaseException as exc:
         # Keep footer aligned with process outcome (main maps unhandled Exception -> exit 2).
@@ -155,9 +181,26 @@ def _run_with_pipeline_progress(
             code = 2
         raise
     finally:
+        renderer.stop()
         _pipeline_footer(subcommand, t0, code)
 
 
+class PipelineProgress:
+    """Progress context handed to ``work``: the renderer + a ready ``on_progress``.
+
+    ``on_progress``/``console`` are wired by :func:`_run_with_pipeline_progress`
+    and should be forwarded to the pipeline helpers' ``on_progress`` /
+    ``on_progress_console`` parameters. ``console`` is the renderer's stderr
+    ``rich.Console`` so the subprocess drain routes non-progress lines through
+    ``console.print`` while the Live region is up (single-writer invariant).
+    """
+
+    def __init__(self, *, renderer: "object | None") -> None:
+        self.renderer = renderer
+        self.on_progress: "Callable | None" = None
+        self.console: "object | None" = None
+
+
 def _jsonable(value: Any) -> Any:
     if hasattr(value, "model_dump"):
         return value.model_dump()
@@ -208,7 +251,7 @@ def _startup_hints(cfg: ResolvedOperatorConfig) -> None:
 
 def _add_index_embedding_flags(p: argparse.ArgumentParser) -> None:
     p.add_argument("--source-root", type=str, default=None, help="Java repository root (default: cwd)")
-    p.add_argument("--index-dir", type=str, default=None, help="Index directory (Lance + Kuzu + cocoindex state)")
+    p.add_argument("--index-dir", type=str, default=None, help="Index directory (Lance + LadybugDB + cocoindex state)")
     p.add_argument("--embedding-model", type=str, default=None, help="Override SBERT_MODEL / YAML embedding.model")
     p.add_argument("--embedding-device", type=str, default=None, help="Override SBERT_DEVICE / YAML embedding.device")
 
@@ -266,7 +309,7 @@ def _cmd_init(args: argparse.Namespace) -> int:
         return 2
     cfg.index_dir.mkdir(parents=True, exist_ok=True)
 
-    def work() -> int:
+    def work(progress: "PipelineProgress | None") -> int:
         env = cfg.subprocess_env()
         verbose = bool(args.verbose)
         coco = run_cocoindex_update(
@@ -275,6 +318,8 @@ def _cmd_init(args: argparse.Namespace) -> int:
             quiet=bool(args.quiet),
             verbose=verbose,
             lance_project_root=None if args.quiet else cfg.source_root,
+            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:
             _emit(
@@ -295,6 +340,8 @@ def _cmd_init(args: argparse.Namespace) -> int:
             verbose=verbose,
             quiet=bool(args.quiet),
             env=env,
+            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 g.returncode != 0:
             _emit(
@@ -310,7 +357,9 @@ def _cmd_init(args: argparse.Namespace) -> int:
         _emit({"success": True, "message": "init completed"})
         return 0
 
-    return _run_with_pipeline_progress("init", cfg, quiet=bool(args.quiet), work=work)
+    return _run_with_pipeline_progress(
+        "init", cfg, quiet=bool(args.quiet), verbose=bool(args.verbose), work=work
+    )
 
 
 def _cmd_increment(args: argparse.Namespace) -> int:
@@ -323,7 +372,7 @@ def _cmd_increment(args: argparse.Namespace) -> int:
     if vectors_only:
         _emit_increment_ladybug_warning()
 
-    def work() -> int:
+    def work(progress: "PipelineProgress | None") -> int:
         env = cfg.subprocess_env()
         coco = run_cocoindex_update(
             env,
@@ -331,6 +380,8 @@ def _cmd_increment(args: argparse.Namespace) -> int:
             quiet=bool(args.quiet),
             verbose=bool(args.verbose),
             lance_project_root=None if args.quiet else cfg.source_root,
+            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:
             _emit(
@@ -356,6 +407,8 @@ def _cmd_increment(args: argparse.Namespace) -> int:
             verbose=bool(args.verbose),
             quiet=bool(args.quiet),
             env=env,
+            on_progress=progress.on_progress if progress is not None else None,
+            on_progress_console=progress.console if progress is not None else None,
         )
 
         # Check if incremental fell back to full rebuild
@@ -389,7 +442,9 @@ def _cmd_increment(args: argparse.Namespace) -> int:
         _emit({"success": True, "message": "increment completed (Lance + graph updated)"})
         return 0
 
-    return _run_with_pipeline_progress("increment", cfg, quiet=bool(args.quiet), work=work)
+    return _run_with_pipeline_progress(
+        "increment", cfg, quiet=bool(args.quiet), verbose=bool(args.verbose), work=work
+    )
 
 
 def _cmd_reprocess(args: argparse.Namespace) -> int:
@@ -397,14 +452,18 @@ def _cmd_reprocess(args: argparse.Namespace) -> int:
     _startup_hints(cfg)
     cfg.apply_to_os_environ()
 
-    def work() -> int:
+    def work(progress: "PipelineProgress | None") -> int:
         env = cfg.subprocess_env()
         verbose = bool(args.verbose)
         vectors_only = bool(getattr(args, "vectors_only", False))
         graph_only = bool(getattr(args, "graph_only", False))
 
         if vectors_only:
-            coco = run_cocoindex_update(env, full_reprocess=True, quiet=bool(args.quiet), verbose=verbose)
+            coco = run_cocoindex_update(
+                env, full_reprocess=True, quiet=bool(args.quiet), verbose=verbose,
+                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 _is_cocoindex_preflight_blocker(coco):
                 payload: dict[str, Any] = {
                     "success": False,
@@ -443,6 +502,8 @@ def _cmd_reprocess(args: argparse.Namespace) -> int:
                 verbose=verbose,
                 quiet=bool(args.quiet),
                 env=env,
+                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 _is_graph_preflight_blocker(g):
                 payload = {
@@ -475,14 +536,23 @@ def _cmd_reprocess(args: argparse.Namespace) -> int:
             _emit_reprocess_outcome(payload, selective_tty_mode="graph" if ok else None)
             return _reprocess_exit_code(payload)
 
-        import server  # lazy: pulls sentence_transformers/torch/lancedb/kuzu
+        import server  # lazy: pulls sentence_transformers/torch/lancedb/ladybug
 
-        result = asyncio.run(server.run_refresh_pipeline(quiet=bool(args.quiet), verbose=verbose))
+        result = asyncio.run(
+            server.run_refresh_pipeline(
+                quiet=bool(args.quiet),
+                verbose=verbose,
+                on_progress=progress.on_progress if progress is not None else None,
+                on_progress_console=progress.console if progress is not None else None,
+            )
+        )
         payload = result.model_dump()
         _emit_reprocess_outcome(payload)
         return _reprocess_exit_code(payload)
 
-    return _run_with_pipeline_progress("reprocess", cfg, quiet=bool(args.quiet), work=work)
+    return _run_with_pipeline_progress(
+        "reprocess", cfg, quiet=bool(args.quiet), verbose=bool(args.verbose), work=work
+    )
 
 
 def _cmd_install(args: argparse.Namespace) -> int:
@@ -495,6 +565,7 @@ def _cmd_install(args: argparse.Namespace) -> int:
         model=args.model,
         source_root=None,  # None means cwd; installer confirms interactively
         quiet=bool(args.quiet),
+        verbose=bool(args.verbose),
     )
 
 
@@ -504,6 +575,8 @@ def _cmd_update(args: argparse.Namespace) -> int:
     return run_update(
         force=bool(args.force),
         dry_run=bool(args.dry_run),
+        quiet=bool(args.quiet),
+        verbose=bool(args.verbose),
     )
 
 
@@ -537,7 +610,7 @@ def _cmd_erase(args: argparse.Namespace) -> int:
             print("Aborted.", file=sys.stderr)
             return 2
 
-    def work() -> int:
+    def work(progress: "PipelineProgress | None") -> int:
         env = cfg.subprocess_env()
         drop = run_cocoindex_drop(env, quiet=bool(args.quiet))
         if drop.returncode == 127:
@@ -570,7 +643,7 @@ def _cmd_erase(args: argparse.Namespace) -> int:
         _emit({"success": True, "message": "erase completed"})
         return 0
 
-    return _run_with_pipeline_progress("erase", cfg, quiet=bool(args.quiet), work=work)
+    return _run_with_pipeline_progress("erase", cfg, quiet=bool(args.quiet), verbose=bool(getattr(args, "verbose", False)), work=work)
 
 
 def _cmd_meta(args: argparse.Namespace) -> int:
@@ -642,7 +715,7 @@ def _cmd_unresolved_calls_list(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     rows = graph.list_unresolved_call_sites(
@@ -663,7 +736,7 @@ def _cmd_unresolved_calls_stats(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     buckets = graph.stats_unresolved_call_sites(by=args.by)
@@ -688,7 +761,7 @@ def _cmd_analyze_pr(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     report = pr_analysis.analyze_pr_pipeline(graph, diff_text)
@@ -728,7 +801,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Create a fresh index from a Java repository.",
         description=(
             "First-time index creation. Refuses if the resolved index directory "
-            "already contains a Kuzu graph or Lance tables. Exit 2 on refusal."
+            "already contains a LadybugDB graph or Lance tables. Exit 2 on refusal."
         ),
     )
     _add_index_embedding_flags(init)
@@ -797,7 +870,7 @@ def build_parser() -> argparse.ArgumentParser:
     increment = subparsers.add_parser(
         "increment",
         help="Pick up changes since the last index update.",
-        description="Runs cocoindex catch-up and incremental Kuzu graph update. Use --vectors-only to skip graph update.",
+        description="Runs cocoindex catch-up and incremental LadybugDB graph update. Use --vectors-only to skip graph update.",
     )
     _add_index_embedding_flags(increment)
     _add_verbosity_flags(increment)
@@ -810,9 +883,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     reprocess = subparsers.add_parser(
         "reprocess",
-        help="Rebuild vectors and/or Kuzu (default: both full phases).",
+        help="Rebuild vectors and/or LadybugDB (default: both full phases).",
         description=(
-            "Default: full Lance reprocess (cocoindex --full-reprocess) then full Kuzu graph rebuild. "
+            "Default: full Lance reprocess (cocoindex --full-reprocess) then full LadybugDB graph rebuild. "
             "Use --vectors-only or --graph-only to run a single phase (mutually exclusive)."
         ),
     )
@@ -834,7 +907,7 @@ def build_parser() -> argparse.ArgumentParser:
     erase = subparsers.add_parser(
         "erase",
         help="Delete the index from disk.",
-        description="Runs cocoindex drop, removes Kuzu, and drops Lance tables. Requires --yes or TTY confirmation.",
+        description="Runs cocoindex drop, removes LadybugDB, and drops Lance tables. Requires --yes or TTY confirmation.",
     )
     _add_index_embedding_flags(erase)
     erase.add_argument("--yes", action="store_true", help="Confirm destructive deletion (required in CI)")

java_codebase_rag/cli_format.py

@@ -1,10 +1,7 @@
 """TTY-aware ANSI formatting for CLI stderr progress."""
 from __future__ import annotations
 
-import itertools
 import sys
-import threading
-import time
 
 _RESET = "\033[0m"
 _BOLD = "\033[1m"
@@ -16,8 +13,6 @@ _CYAN = "\033[36m"
 CHECK = "✓"
 CROSS = "✗"
 
-_SPINNER_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
-
 _NOISE_CONTAINS: tuple[bytes, ...] = (
     b"lance::",
     b"FutureWarning",
@@ -25,6 +20,14 @@ _NOISE_CONTAINS: tuple[bytes, ...] = (
     b'"event": "brownfield-',
     b"unknown producer source strategy",
     b"unknown client source strategy",
+    # Builder verbose heartbeats / pass banners: in default mode the renderer's
+    # bar subsumes these, so they must NOT also appear as raw lines above the
+    # Live region. --verbose raw-relay bypasses this filter and still shows them.
+    b"[graph] pass ",
+    b"[graph] scoped write ",
+    b"[graph] writing ",
+    b"[graph] done ",
+    b"[increment] ",
 )
 
 
@@ -80,33 +83,3 @@ def styled_check() -> str:
 
 def styled_cross() -> str:
     return red(CROSS) if stderr_is_tty() else CROSS
-
-
-class Spinner:
-    """Braille spinner that overwrites the current stderr line until stopped."""
-
-    def __init__(self, label: str) -> None:
-        self._label = label
-        self._stop = threading.Event()
-        self._thread: threading.Thread | None = None
-
-    def start(self) -> None:
-        self._thread = threading.Thread(target=self._run, name="spinner", daemon=True)
-        self._thread.start()
-
-    def stop(self) -> None:
-        self._stop.set()
-        if self._thread is not None:
-            self._thread.join(timeout=2.0)
-        sys.stderr.buffer.write(b"\r\x1b[2K")
-        sys.stderr.buffer.flush()
-
-    def _run(self) -> None:
-        frames = itertools.cycle(_SPINNER_FRAMES)
-        t0 = time.monotonic()
-        while not self._stop.wait(0.3):
-            elapsed = time.monotonic() - t0
-            frame = next(frames)
-            line = f"\r{frame} {self._label} · {elapsed:.0f}s"
-            sys.stderr.buffer.write(line.encode())
-            sys.stderr.buffer.flush()

java_codebase_rag/cli_progress.py

@@ -3,26 +3,10 @@ from __future__ import annotations
 
 import asyncio
 import sys
+from typing import Callable
 
-from java_codebase_rag.cli_format import bold_cyan, is_noise_line, styled_check, styled_cross
-
-
-def emit_vectors_start() -> None:
-    print(
-        bold_cyan("[vectors]") + " running · cocoindex update",
-        file=sys.stderr,
-        flush=True,
-    )
-
-
-def emit_vectors_finish(*, elapsed_s: float, exit_code: int) -> None:
-    marker = styled_check() if exit_code == 0 else styled_cross()
-    print(
-        f"{marker} {bold_cyan('[vectors]')} finished · {elapsed_s:.2f}s"
-        + (f" (exit={exit_code})" if exit_code != 0 else ""),
-        file=sys.stderr,
-        flush=True,
-    )
+from java_codebase_rag.cli_format import is_noise_line
+from java_codebase_rag.progress import ProgressEvent, make_relay
 
 
 class _AsyncLineFilter:
@@ -61,8 +45,15 @@ async def accumulate_and_relay_subprocess_streams(
     *,
     relay: bool,
     verbose: bool = True,
+    on_progress: Callable[[ProgressEvent], None] | None = None,
+    on_progress_console: object | None = None,
 ) -> tuple[bytes, bytes]:
-    """Read stdout and stderr until EOF; optionally copy non-noise stderr chunks to stderr."""
+    """Read stdout and stderr until EOF; optionally copy non-noise stderr chunks to stderr.
+
+    When ``on_progress`` is set, stderr is drained through a :class:`ProgressRelay`
+    so ``JCIRAG_PROGRESS`` lines are parsed and routed to ``on_progress`` (and
+    suppressed from the relay), matching the sync ``pipeline._popen_capturing_stderr``.
+    """
     stdout = proc.stdout
     stderr = proc.stderr
     if stdout is None or stderr is None:
@@ -70,7 +61,12 @@ async def accumulate_and_relay_subprocess_streams(
 
     out_buf = bytearray()
     err_buf = bytearray()
-    filt = _AsyncLineFilter() if (relay and not verbose) else None
+    if on_progress is not None:
+        filt = make_relay(on_progress, console=on_progress_console, verbose=verbose)
+    elif relay and not verbose:
+        filt = _AsyncLineFilter()
+    else:
+        filt = None
 
     async def drain_stdout(reader: asyncio.StreamReader, target: bytearray) -> None:
         while True:

java_codebase_rag/install_data/agents/explorer-rag-enhanced.md

@@ -151,15 +151,15 @@ Simple types in parentheses; generics erased. No spaces after commas. No-arg: `(
 
 ### Shared NodeFilter
 
-For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`.
+For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`; invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed.
 
 | Keys | Applies to |
 | ---- | ---------- |
 | `microservice`, `module` | All kinds |
 | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` | **symbol** |
 | `http_method`, `path_prefix`, `framework` | **route** |
-| `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
-| `producer_kind`, `topic_prefix` | **producer** |
+| `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
+| `source_layer`, `producer_kind`, `topic_prefix` | **producer** |
 
 No wildcards in prefix fields — use `search(query=…)` for fuzzy text.
 

java_codebase_rag/install_data/skills/explore-codebase/SKILL.md

@@ -125,15 +125,15 @@ Use these strings **verbatim** in `neighbors(..., edge_types=[...])`.
 
 ### NodeFilter (`find`, `search.filter`, `neighbors.filter`)
 
-For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`.
+For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`; invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed.
 
 | Applicable to | Keys |
 | ------------- | ---- |
 | All kinds | `microservice`, `module` |
 | **symbol** only | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` |
 | **route** only | `http_method`, `path_prefix`, `framework` |
-| **client** only | `client_kind`, `target_service`, `target_path_prefix`, `http_method` |
-| **producer** only | `producer_kind`, `topic_prefix` |
+| **client** only | `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` |
+| **producer** only | `source_layer`, `producer_kind`, `topic_prefix` |
 
 No wildcards in prefix fields — use `search(query=…)` for ranked text.
 
@@ -166,8 +166,8 @@ Exclude `DTO`, `OTHER`, `MAPPER` with `exclude_roles` when tracing business logi
 
 **Symbol kinds:** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
 
-**Route frameworks:** `spring_mvc`, `webflux`, `kafka`, `rabbitmq`, `jms`, `stream`, `codebase_async_route`, …
-**Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`.
+**Route frameworks:** `spring_mvc`, `webflux`. (Route *kinds* are `http_endpoint`, `http_consumer`, `kafka_topic`, `rabbit_queue`, `jms_destination`, `stream_binding`.)
+**Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`. **Source layers (client/producer):** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
 **Match types:** `cross_service`, `intra_service`, `ambiguous`, `phantom`, `unresolved`.
 
 ---