java-codebase-rag 0.12.0__py3-none-any.whl → 0.12.2__py3-none-any.whl

java_codebase_rag/cli_dispatch.py

@@ -1,251 +0,0 @@
-"""Unified ``jrag`` CLI dispatcher (Task 2 of the rename).
-
-The tool exposes two disjoint CLI surfaces that this module unifies behind a
-single ``jrag`` console-script entry point:
-
-* :mod:`java_codebase_rag.cli` — operator / lifecycle verbs (``init``,
-  ``install``, ``update``, ``increment``, ``reprocess``, ``erase``, ``meta``,
-  ``tables``, ``diagnose-ignore``, ``analyze-pr``, ``unresolved-calls``).
-* :mod:`java_codebase_rag.jrag` — agent verbs (``find``, ``search``,
-  ``inspect``, ``callers``, ``callees``, ``hierarchy``, ``watch``, ``status``,
-  … — 32 verbs total).
-
-Both modules already expose a zero-argument ``_console_script_main`` that
-reads ``sys.argv`` itself, performs its own startup (``raise_fd_limit``, UTF-8
-stdio, error handling), and calls ``sys.exit`` (via ``os._exit``). This
-dispatcher does NOT reimplement argparse, fd-limit, or error handling: it picks
-the target module and forwards. Letting the chosen ``_console_script_main`` run
-unwinds as normal, including its ``SystemExit`` / ``os._exit``.
-
-Routing contract
-----------------
-For an invocation ``[argv0, *args]``:
-
-* If any token in ``args`` is a member of :data:`OPERATOR_VERBS`, route to
-  ``cli._console_script_main``.
-* Else if any token is a member of :data:`AGENT_VERBS`, route to
-  ``jrag._console_script_main``.
-* Otherwise fall back to the identity default: the basename of ``argv0``.
-  ``jrag`` → ``jrag._console_script_main``; anything else (including the
-  legacy ``java-codebase-rag`` alias) → ``cli._console_script_main``.
-
-The "first matching verb" rule scans left-to-right and routes by *that* verb's
-set. Operator and agent verb sets are disjoint, so the scan is unambiguous.
-
-Known non-goal: if a global flag's value token happens to equal a verb name
-(e.g. a hypothetical ``--config find``), routing may follow the verb heuristic.
-Acceptable edge case — the alternative (a flag-aware parser) would duplicate
-argparse here, which the design explicitly forbids.
-
-Unified help contract
----------------------
-For the canonical ``jrag`` identity, a top-level help request (``jrag``,
-``jrag --help``, ``jrag -h`` — i.e. ``-h``/``--help`` appears before any
-recognized verb, or no tokens at all) is served by :func:`_print_unified_help`:
-it prints the agent parser's full help (agent verbs + global flags) and
-appends a clearly labeled "Operator commands" section listing the operator
-verbs with one-line descriptions sourced from :func:`cli.build_parser`'s
-subparser choices. This makes ``jrag --help`` the single discovery surface for
-all 11+32 verbs, satisfying the unification design contract.
-
-The legacy ``java-codebase-rag`` alias does NOT get unified help: it keeps its
-pre-rename behavior (operator-only parser) for backward compatibility, since
-operators with shell scripts that parse ``java-codebase-rag --help`` output
-must not see new verbs appear under that alias.
-
-Before routing, :func:`maybe_warn_legacy_alias` runs once. It is a no-op
-unless the tool was invoked through a legacy alias in an interactive context
-(see :mod:`java_codebase_rag._deprecation`); in tests ``sys.stderr`` is not a
-TTY so it stays silent.
-"""
-from __future__ import annotations
-
-import argparse
-import sys
-from typing import Callable
-
-from java_codebase_rag import cli as _cli_mod
-from java_codebase_rag import jrag as _jrag_mod
-from java_codebase_rag._deprecation import _invoked_program_name
-from java_codebase_rag._deprecation import maybe_warn_legacy_alias
-
-__all__ = [
-    "OPERATOR_VERBS",
-    "AGENT_VERBS",
-    "_console_script_main",
-]
-
-#: Tokens that request top-level help. argparse's default help action accepts
-#: both ``-h`` and ``--help`` (neither parser disables ``add_help``).
-_HELP_TOKENS: frozenset[str] = frozenset({"-h", "--help"})
-
-
-#: Operator / lifecycle verbs. Must match ``cli.build_parser()``'s registered
-#: top-level subcommand choice names (drift-guarded by the test suite).
-#:
-#: Note: the rename design spec lists ``diagnose`` and ``unresolved`` here, but
-#: the parser actually registers ``diagnose-ignore`` and ``unresolved-calls``
-#: (the spec abbreviated the names). The drift-guard test pins the dispatcher
-#: to the parser's truth, so the hyphenated names are what we ship.
-OPERATOR_VERBS: frozenset[str] = frozenset(
-    {
-        "init",
-        "install",
-        "update",
-        "increment",
-        "reprocess",
-        "erase",
-        "meta",
-        "tables",
-        "diagnose-ignore",
-        "analyze-pr",
-        "unresolved-calls",
-    }
-)
-
-#: Agent verbs. Must match ``jrag.build_parser()``'s registered top-level
-#: subcommand choice names (drift-guarded by the test suite).
-AGENT_VERBS: frozenset[str] = frozenset(
-    {
-        "find",
-        "search",
-        "inspect",
-        "callers",
-        "callees",
-        "hierarchy",
-        "implementations",
-        "subclasses",
-        "overrides",
-        "overridden-by",
-        "dependents",
-        "impact",
-        "decompose",
-        "flow",
-        "dependencies",
-        "connection",
-        "outline",
-        "imports",
-        "microservices",
-        "map",
-        "conventions",
-        "overview",
-        "vocab-index",
-        "watch",
-        "status",
-        "http-routes",
-        "http-clients",
-        "producers",
-        "topics",
-        "jobs",
-        "listeners",
-        "entities",
-    }
-)
-
-
-def _is_unified_help_request() -> bool:
-    """True iff argv is a top-level help/no-args request.
-
-    Returns True when ``sys.argv[1:]`` is empty (no-args) OR contains
-    ``-h``/``--help`` as the first recognized token (i.e. before any verb).
-    Returns False as soon as a verb token is seen, so verb-specific help
-    (``jrag install --help``, ``jrag find --help``) still routes to the
-    verb's own parser. Also returns False for non-help requests such as
-    ``jrag --version`` (no help token, no verb — falls through to the
-    identity default).
-    """
-    rest = sys.argv[1:] if len(sys.argv) > 1 else []
-    if not rest:
-        return True
-    for token in rest:
-        if token in OPERATOR_VERBS or token in AGENT_VERBS:
-            return False
-        if token in _HELP_TOKENS:
-            return True
-    return False
-
-
-def _operator_subcommand_helps() -> list[tuple[str, str]]:
-    """Return ``[(verb, one_line_help), ...]`` for operator verbs, parser order.
-
-    Pulls the ``(metavar, help)`` of each ``_ChoicesPseudoAction`` registered
-    on ``cli.build_parser()``'s top-level subparsers action. Parser order
-    (lifecycle flow: ``init``, ``install``, ``update``, ...) is preserved
-    rather than sorting alphabetically.
-    """
-    parser = _cli_mod.build_parser()
-    for action in parser._actions:
-        if isinstance(action, argparse._SubParsersAction):
-            return [(ca.metavar, ca.help or "") for ca in action._choices_actions]
-    return []
-
-
-def _print_unified_help(stream=None) -> None:
-    """Print the canonical ``jrag`` unified help: agent verbs + operator verbs.
-
-    Prints the agent parser's full help (which already lists the 32 agent
-    verbs with one-line descriptions plus the global ``-h``/``--version``
-    options and the descriptive epilog), then appends a clearly labeled
-    "Operator commands (indexing & maintenance)" section listing the 11
-    operator verbs with their one-line descriptions sourced from
-    :func:`cli.build_parser`'s subparser choices.
-
-    Writes to ``stream`` (default ``sys.stdout``) and returns without exiting
-    — the caller (``_console_script_main``) returns to the pip wrapper, which
-    exits 0.
-    """
-    target = stream if stream is not None else sys.stdout
-    agent_parser = _jrag_mod.build_parser()
-    agent_parser.print_help(target)
-    target.write("\n")
-    target.write(
-        "Operator commands (indexing & maintenance; run `jrag <command> --help` "
-        "for details):\n"
-    )
-    for name, help_text in _operator_subcommand_helps():
-        target.write(f"    {name:<20} {help_text}\n")
-
-
-def _choose_target() -> Callable[[], None]:
-    """Pick the ``_console_script_main`` to delegate to.
-
-    Scans ``sys.argv[1:]`` left-to-right for the first token that is a member
-    of ``OPERATOR_VERBS`` or ``AGENT_VERBS``; routes by that set. If no token
-    matches, routes by identity default (``jrag`` basename → jrag; anything
-    else → cli, including the legacy ``java-codebase-rag`` alias).
-    """
-    rest = sys.argv[1:] if len(sys.argv) > 1 else []
-    for token in rest:
-        if token in OPERATOR_VERBS:
-            return _cli_mod._console_script_main
-        if token in AGENT_VERBS:
-            return _jrag_mod._console_script_main
-
-    # No verb token: identity default by argv[0] basename.
-    if _invoked_program_name() == "jrag":
-        return _jrag_mod._console_script_main
-    return _cli_mod._console_script_main
-
-
-def _console_script_main() -> None:
-    """Unified ``jrag`` entry point: warn, maybe serve unified help, delegate.
-
-    For the canonical ``jrag`` identity with a top-level help/no-args request,
-    print the unified help (agent verbs + operator verbs) and return — the pip
-    wrapper then exits 0. This is the discovery surface for all verbs.
-
-    Otherwise: pick the target module and forward. The chosen target's
-    ``_console_script_main`` does its own startup and terminates the process
-    (via ``os._exit``); we let ``SystemExit`` propagate rather than
-    reimplementing startup here.
-    """
-    maybe_warn_legacy_alias()
-    if _invoked_program_name() == "jrag" and _is_unified_help_request():
-        _print_unified_help()
-        return
-    target = _choose_target()
-    target()
-
-
-if __name__ == "__main__":  # pragma: no cover - direct invocation
-    _console_script_main()

java_codebase_rag/cli_format.py

@@ -1,85 +0,0 @@
-"""TTY-aware ANSI formatting for CLI stderr progress."""
-from __future__ import annotations
-
-import sys
-
-_RESET = "\033[0m"
-_BOLD = "\033[1m"
-_DIM = "\033[2m"
-_GREEN = "\033[32m"
-_RED = "\033[31m"
-_CYAN = "\033[36m"
-
-CHECK = "✓"
-CROSS = "✗"
-
-_NOISE_CONTAINS: tuple[bytes, ...] = (
-    b"lance::",
-    b"FutureWarning",
-    b"Loading weights:",
-    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] ",
-)
-
-
-def is_noise_line(line: bytes) -> bool:
-    return any(p in line for p in _NOISE_CONTAINS)
-
-
-def stderr_is_tty() -> bool:
-    return hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
-
-
-def _styled(text: str, *codes: str) -> str:
-    if not stderr_is_tty():
-        return text
-    return "".join(codes) + text + _RESET
-
-
-def bold(text: str) -> str:
-    return _styled(text, _BOLD)
-
-
-def dim(text: str) -> str:
-    return _styled(text, _DIM)
-
-
-def green(text: str) -> str:
-    return _styled(text, _GREEN)
-
-
-def red(text: str) -> str:
-    return _styled(text, _RED)
-
-
-def cyan(text: str) -> str:
-    return _styled(text, _CYAN)
-
-
-def bold_green(text: str) -> str:
-    return _styled(text, _BOLD, _GREEN)
-
-
-def bold_red(text: str) -> str:
-    return _styled(text, _BOLD, _RED)
-
-
-def bold_cyan(text: str) -> str:
-    return _styled(text, _BOLD, _CYAN)
-
-
-def styled_check() -> str:
-    return green(CHECK) if stderr_is_tty() else CHECK
-
-
-def styled_cross() -> str:
-    return red(CROSS) if stderr_is_tty() else CROSS

java_codebase_rag/cli_progress.py

@@ -1,94 +0,0 @@
-"""CLI-owned stderr progress lines (shared by server reprocess path and pipeline helpers)."""
-from __future__ import annotations
-
-import asyncio
-import sys
-from typing import Callable
-
-from java_codebase_rag.cli_format import is_noise_line
-from java_codebase_rag.progress import ProgressEvent, make_relay
-
-
-class _AsyncLineFilter:
-    """Buffers byte chunks and relays only non-noise lines to stderr (async drain path)."""
-
-    def __init__(self) -> None:
-        self._buf = bytearray()
-        self._suppress_next = False
-
-    def feed(self, chunk: bytes) -> None:
-        self._buf.extend(chunk)
-        while b"\n" in self._buf:
-            line, self._buf = self._buf.split(b"\n", 1)
-            line += b"\n"
-            noise = is_noise_line(line)
-            if noise:
-                self._suppress_next = True
-                continue
-            if self._suppress_next and line[:1] in (b" ", b"\t"):
-                continue
-            self._suppress_next = False
-            sys.stderr.buffer.write(line)
-            sys.stderr.buffer.flush()
-
-    def flush(self) -> None:
-        if self._buf:
-            if not is_noise_line(self._buf):
-                sys.stderr.buffer.write(bytes(self._buf))
-                sys.stderr.buffer.flush()
-            self._buf.clear()
-        self._suppress_next = False
-
-
-async def accumulate_and_relay_subprocess_streams(
-    proc: asyncio.subprocess.Process,
-    *,
-    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.
-
-    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:
-        raise RuntimeError("subprocess must be created with stdout=PIPE and stderr=PIPE")
-
-    out_buf = bytearray()
-    err_buf = bytearray()
-    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:
-            chunk = await reader.read(65536)
-            if not chunk:
-                break
-            target.extend(chunk)
-
-    async def drain_stderr(reader: asyncio.StreamReader, target: bytearray) -> None:
-        while True:
-            chunk = await reader.read(65536)
-            if not chunk:
-                break
-            target.extend(chunk)
-            if filt is not None:
-                filt.feed(chunk)
-            elif relay:
-                sys.stderr.buffer.write(chunk)
-                sys.stderr.buffer.flush()
-
-    await asyncio.gather(drain_stdout(stdout, out_buf), drain_stderr(stderr, err_buf))
-    await proc.wait()
-    if filt is not None:
-        filt.flush()
-    return bytes(out_buf), bytes(err_buf)