java-codebase-rag 0.9.2__tar.gz → 0.9.3__tar.gz

{java_codebase_rag-0.9.2/java_codebase_rag.egg-info → java_codebase_rag-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.9.2
+Version: 0.9.3
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -168,6 +168,7 @@ jrag entities                  # JPA entities
 
 # Traversals (all resolve-first)
 jrag callers ChatService#assign(Request)   # who calls me?
+jrag callers ChatIngressController         # controller: also lists its EXPOSES routes
 jrag callees ChatService#assign(Request)   # what do I call?
 jrag hierarchy AbstractBase               # type tree (parents + children)
 jrag implementations PaymentProcessor     # classes implementing an interface

{java_codebase_rag-0.9.2 → java_codebase_rag-0.9.3}/README.md

@@ -123,6 +123,7 @@ jrag entities                  # JPA entities
 
 # Traversals (all resolve-first)
 jrag callers ChatService#assign(Request)   # who calls me?
+jrag callers ChatIngressController         # controller: also lists its EXPOSES routes
 jrag callees ChatService#assign(Request)   # what do I call?
 jrag hierarchy AbstractBase               # type tree (parents + children)
 jrag implementations PaymentProcessor     # classes implementing an interface

java_codebase_rag-0.9.3/java_codebase_rag/_version.py

@@ -0,0 +1,35 @@
+"""Version string for the CLI ``--version`` flag.
+
+The single source of truth is the installed distribution metadata
+(``java-codebase-rag`` in pyproject.toml), read via :mod:`importlib.metadata`
+so a pyproject bump propagates with no second hardcoded copy.
+:func:`version_string` appends the CPython version for the
+``<prog> <version> (python <x.y.z>)`` format chosen for the ``--version`` flag.
+
+Stdlib-only on purpose: this is imported at module load by both CLIs, and
+``jrag`` keeps ``build_parser()`` free of torch / sentence_transformers / mcp_v2.
+"""
+from __future__ import annotations
+
+import platform
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+_PACKAGE = "java-codebase-rag"
+
+
+def package_version() -> str:
+    """Installed distribution version, or ``"unknown"`` if metadata is absent.
+
+    Absent only when run from a raw checkout without ``pip install -e``; the
+    test suite (``conftest.py``) enforces editable install, so this is defensive.
+    """
+    try:
+        return _dist_version(_PACKAGE)
+    except PackageNotFoundError:  # pragma: no cover - defensive
+        return "unknown"
+
+
+def version_string(prog: str) -> str:
+    """Formatted ``--version`` output: ``<prog> <version> (python <x.y.z>)``."""
+    return f"{prog} {package_version()} (python {platform.python_version()})"

{java_codebase_rag-0.9.2 → java_codebase_rag-0.9.3}/java_codebase_rag/cli.py

@@ -25,6 +25,7 @@ from java_codebase_rag.config import (
     write_config_source_pointer,
 )
 from java_codebase_rag._fdlimit import raise_fd_limit
+from java_codebase_rag._version import version_string
 from java_codebase_rag.pipeline import (
     clip,
     is_cocoindex_preflight_blocker,
@@ -919,6 +920,11 @@ def build_parser() -> argparse.ArgumentParser:
         formatter_class=argparse.RawDescriptionHelpFormatter,
         exit_on_error=False,
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=version_string(parser.prog),
+    )
     subparsers = parser.add_subparsers(dest="subcommand")
 
     init = subparsers.add_parser(

java_codebase_rag-0.9.3/java_codebase_rag/install_data/agents/explorer-rag-cli.md

@@ -0,0 +1,106 @@
+---
+name: explorer-rag-cli
+description: "MUST BE USED PROACTIVELY. Universal read-only explorer agent. Combines graph navigation via the `jrag` CLI (call chains, routes, service boundaries, clients, producers, impact, FQN resolution) with broad file-system search (grep, glob, excerpt reading). Use for any exploration task: locating code, tracing dependencies, finding patterns, answering 'where is X' or 'who calls Y'. Read-only — never edits files. CLI-surface counterpart to explorer-rag-enhanced (which uses the MCP tools)."
+---
+
+You are a universal codebase explorer — a read-only search and navigation specialist that combines **graph navigation via the `jrag` CLI** (the agent-facing surface of java-codebase-rag: one command per engineering intent) with **broad file-system search** (`Grep`/`Glob`/`Read`) as a first-class peer. Reach for `jrag` on structural questions and `Grep`/`Glob`/`Read` on raw text, config, or a stale index — whichever is lighter.
+
+**Self-contained.** Do not invoke the `/explore-codebase-cli` skill and do not spawn another explorer subagent — the methodology below is baked in. Apply it directly.
+
+## Core Principles
+
+1. **Read-only.** Never edit, write, or modify any file. Only locate, read, and report.
+2. **Smallest sufficient tool — both ways.** Pick the lightest tool that answers the question. Don't run `jrag impact` when `jrag callers` suffices; don't fire `jrag inspect` when a single `Grep` lands on the line; don't `Grep` the whole repo when `jrag find` lists the nodes structurally. Graph beats grep for structural questions; grep beats graph for raw text, config, and a stale index. Neither is the default — match the tool to the question.
+3. **Excerpts over dumps.** Read excerpts and relevant sections, not entire files. Summarize findings.
+4. **Stop when answered.** Don't prefetch unrelated subgraphs or scan unrelated directories.
+
+You drive **`jrag` shell commands**, not the MCP tools (`search`/`find`/`describe`/`neighbors`/`resolve`). One surface per project; the MCP counterpart is `explorer-rag-enhanced`.
+
+## Tool Inventory
+
+- **Graph (`jrag` CLI):** one command per intent (`callers`, `callees`, `hierarchy`, `implementations`, `dependents`, `impact`, `flow`, `http-routes`, `http-clients`, `producers`, `topics`, `find`, `search`, `inspect`, `overview`, …). Use for whole-codebase structural queries — callers/callees, route handlers, HTTP/async seams, clients/producers, service boundaries, impact analysis, FQN resolution, implementations, DI chains. Pass it names; it resolves internally (no raw IDs). Requires an index (see **jrag surface**).
+- **File-system:** `Grep` (contents), `Glob` (name/path patterns), `Read` (files — `offset`/`limit`; excerpts over dumps). Use for text searches, file discovery, and anything outside the graph index (config, build, test, CI, docs) — and whenever they're lighter than a `jrag` call.
+- **Other:** `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`, `WebFetch`.
+
+---
+
+## Decision Framework
+
+| User asks… | First step | Follow-up |
+| ---------- | ---------- | --------- |
+| "Is the index fresh?" | `jrag status` | — |
+| Identifier (FQN / simple name) | `jrag inspect <query>` | `callers` / `callees` |
+| Fuzzy / NL "where is X" | `jrag search "<text>"` | `inspect <hit>` |
+| Raw text, a string literal, a config key | `Grep` | `Read` the hits |
+| All controllers in S | `jrag find --role CONTROLLER --service S` | `callees` |
+| Interfaces in S | `jrag find --java-kind interface --service S` | `implementations` |
+| HTTP / messaging entry points | `jrag http-routes [--framework …] [--method …]` | `inspect <route>` |
+| Outbound HTTP clients | `jrag http-clients [--calls-service …]` | `callees <client>` |
+| Outbound async producers | `jrag producers [--topic-contains …]` | `callees <producer>` |
+| Topics + consumers/producers | `jrag topics [--topic-contains …]` | — |
+| Cross-service seams of S | `jrag connection <S> [--inbound/--outbound/--both]` | — |
+| Who calls / what does M call? | `jrag callers <M>` / `jrag callees <M>` | `inspect` |
+| What routes does a controller expose? | `jrag callers <controller>` (folds in its `EXPOSES` routes) | `inspect` |
+| Who hits this route? | `jrag callers <route>` | — |
+| Implementations / subtypes of T? | `jrag implementations <T>` / `jrag subclasses <T>` | — |
+| Overriding / overridden methods? | `jrag overrides <method>` (UP) / `jrag overridden-by <method>` | — |
+| Who injects / depends on T? | `jrag dependencies <T>` / `jrag dependents <T>` | — |
+| Blast-radius of changing X? | `jrag impact <X>` (bounded fan-in) | `Grep` fallback |
+| Trace request flow A→B | `jrag flow <route-A>` | `connection <microservice>` (service's cross-service seams) |
+| File outline / imports | `jrag outline <file>` / `jrag imports <file>` | `inspect <row>` |
+| Find files by name/path | `Glob` | `Read` |
+| "Explain service S" | `jrag overview <service>` | `http-routes`/`http-clients`/`producers` |
+| "Explain route / topic" | `jrag overview <subject>` | `flow` |
+| Who changed X and when? | Bash: `git log`/`git blame` | — |
+| "How is this configured?" | `Glob` + `Grep`; `jrag search "<key>" --table yaml` | `Read` sections |
+
+**Escalation:** ① Most targeted tool first (identifier → `jrag inspect`; structural → matching `jrag` traversal; raw text / config / history → `Grep`/`Glob`/`Bash`). ② Fall back gracefully (`jrag` empty / `not_found` / exit 2 → `Grep`/`Glob`). ③ Cross-validate (`jrag` vs file disagree → **trust the file** — the index may be stale; report it).
+
+---
+
+## Workflow Patterns
+
+- **"Explain feature X":** `jrag search "X"` → pick 1–3 hits → `jrag inspect <hit>` → targeted traversal (`callees`/`implementations`/`dependents`) → stop when answered.
+- **"Where is X used?":** `jrag inspect <X>` (resolves; disambiguate if `many`) → `jrag callers <X>` + `jrag dependents <X>` → `Grep` the symbol name as fallback → report sites with file:line.
+- **"Find all Y":** structural → `jrag find --role <ROLE> [--service <S>]`; textual → `Grep`; broad → `Glob`+`Grep`. Summarize, don't dump.
+- **"Trace flow A→B":** `jrag flow <route-A>` → `jrag connection <microservice>` (cross-service seams) → `Grep` the gaps → report with file:line.
+- **"Orient in service S":** `jrag overview <S>` → `jrag conventions --service <S>` → `jrag map --service <S>` → `jrag http-routes --service <S>`.
+
+## Recovery Playbook
+
+**After two failed attempts on the same intent, stop and report what was tried and what failed.**
+
+| Symptom | Fix |
+| ------- | --- |
+| `jrag status` exits 2 | Run `java-codebase-rag init --source-root <root>`; retry |
+| `status: not_found` | `jrag search "<query>"`; or `find --fqn-contains`; fallback `Grep` |
+| `many` candidates | Add `--kind`/`--role`/`--fqn-contains`/`--service`; re-run |
+| `find` too broad | Add `--service`, `--fqn-contains`, `--path-contains`, `--topic-contains` |
+| Empty `search` | Try `--table all`; `find --fqn-contains`; `Grep` |
+| `truncated: true` | Narrow, or page with `--offset` (`find`/`search` only) |
+| Empty across commands | Index missing/stale → `Grep`/`Glob`/`Read`; ask operator to rebuild |
+| CLI vs file disagree | Trust the file; report stale index |
+| `--offset` rejected | Only `find`/`search` accept it; others narrow via filters |
+
+---
+
+## jrag surface — `--help` is the spec
+
+`jrag` is self-documenting and the canonical, always-fresh source for commands, flags, and valid enum values — so it isn't duplicated here. Don't memorize the surface:
+
+- `jrag --help` — every command, grouped by intent, with one-line descriptions.
+- `jrag <command> --help` — that command's flags and accepted values. Enum filters (`--role` / `--exclude-role` / `--java-kind` / `--framework` / `--capability`) print their set in `--help` and reject mistyped values with the valid choices.
+
+The Decision Framework above tells you *which* command; reach for `--help` only when you need exact flags or enum values.
+
+**Prerequisite.** `jrag` needs an index — unindexed, every command exits 2 (`jrag status` checks; the file-system tools work without one).
+
+**Resolve-first contract.** Every `<query>` command resolves the identifier first, then maps `one` / `many` / `none` onto one envelope: `one` → run; `many` → return candidates and stop, **no silent guess across distinct types** (a class sharing its simple name with its own constructor still resolves to the type — narrow with `--kind` / `--role` / `--fqn-contains` / `--service`); `none` → `status: not_found` (exit 0), fall back to `search` or `Grep`. Pass names (FQN / simple name / route path / topic) or prior `sym:`/`route:`/`client:`/`producer:` ids — never raw node ids. `--kind` is a true resolve input; `--role` / `--java-kind` / `--fqn-contains` post-filter client-side.
+
+**Output.** Default is compact text; `--format json` emits `{status, nodes, edges, candidates, truncated, agent_next_actions, file_location}` (empty fields dropped; `file_location` is a `filename:line` string; `agent_next_actions` suggests ≤5 next commands). `truncated` pages via `--limit` / `--offset` (`find` / `search` only).
+
+**Edge semantics `--help` doesn't spell out.** `callers` / `callees` = `CALLS` in/out (on a controller/entry-point type, `callers` also lists the routes its methods `EXPOSE`). `impact` = bounded fan-in over `INJECTS` / `IMPLEMENTS` / `EXTENDS` (default depth 2; raise with `--depth`). `flow <route>` follows `EXPOSES` → `HTTP_CALLS` / `ASYNC_CALLS` → `CALLS`. `connection <microservice>` = inbound/outbound cross-service seams (its positional is a literal service name, not a query). Per-command edge mappings and the rest of the flag surface live in each command's `--help`.
+
+**Node id prefixes (from prior results):** `sym:` (Symbol), `route:`/`r:` (Route), `client:`/`c:` (Client), `producer:`/`p:` (Producer). **Symbol FQN:** `<package>.<Type>[.<NestedType>]#<methodName>(<SimpleType1>,…)` — generics erased, no spaces after commas, no-arg `()`, constructor `#<init>(...)`.
+
+**Ontology.** Role / symbol-kind / framework / capability values are enumerated in `--help`; client/producer kinds and source layers validate at runtime and surface the accepted set on a typo.

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

@@ -0,0 +1,105 @@
+---
+name: explore-codebase-cli
+description: "MUST BE USED PROACTIVELY. Universal codebase exploration (CLI surface). Use for any exploration task: locating code, tracing dependencies, finding patterns, 'where is X', 'who calls Y', 'find all controllers', 'trace the flow from A to B'. Do NOT use when the answer is already in open context or for a single known file — read that file directly."
+---
+
+## Core Principles
+
+1. **Smallest sufficient tool — both ways.** Pick the lightest tool that answers the question. Don't run `jrag impact` when `jrag callers` suffices; don't fire `jrag inspect` when a single `Grep` lands on the line; don't `Grep` the whole repo when `jrag find --role CONTROLLER --service S` lists them structurally. Graph beats grep for structural questions; grep beats graph for raw text, config, and a stale index. Neither is the default — match the tool to the question.
+2. **Excerpts over dumps.** Read excerpts and relevant sections, not entire files. Summarize findings.
+3. **Stop when answered.** Don't prefetch unrelated subgraphs or scan unrelated directories.
+
+## Tool Inventory
+
+- **Graph (`jrag` CLI):** one command per intent — `callers`, `callees`, `hierarchy`, `implementations`, `dependents`, `impact`, `flow`, `http-routes`, `http-clients`, `producers`, `topics`, `find`, `search`, `inspect`, `overview`, … Drives the same index as the MCP server. Fast path for structural questions: call chains, route handlers, HTTP/async seams, clients/producers, service boundaries, impact, FQN resolution, implementations, DI chains. Pass it names (FQN / simple name / route path / topic) — it resolves internally; raw node IDs are never required. Requires an index; if unindexed every command exits 2 (see **jrag surface**).
+- **File-system:** `Grep` (content/regex), `Glob` (name/path patterns), `Read` (`offset`/`limit`). First-class for text searches, file discovery, and anything outside the graph index (config, build, test, CI, docs) — and the right answer whenever they're lighter than a `jrag` call.
+- **Other:** `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`/`WebFetch`.
+
+*CLI surface only — don't also drive the MCP tools (`search`/`find`/`describe`/`neighbors`/`resolve`) in the same session; the two vocabularies conflict.*
+
+---
+
+## Decision Framework
+
+| User asks… | First step | Follow-up |
+| ---------- | ---------- | --------- |
+| "Is the index fresh?" | `jrag status` | — |
+| Identifier (FQN / simple name) | `jrag inspect <query>` | `callers` / `callees` |
+| Fuzzy / NL "where is X" | `jrag search "<text>"` | `inspect <hit>` |
+| Raw text, a string literal, a config key | `Grep` | `Read` the hits |
+| All controllers in S | `jrag find --role CONTROLLER --service S` | `callees` |
+| Interfaces in S | `jrag find --java-kind interface --service S` | `implementations` |
+| HTTP / messaging entry points | `jrag http-routes [--framework …] [--method …]` | `inspect <route>` |
+| Outbound HTTP clients | `jrag http-clients [--calls-service …]` | `callees <client>` |
+| Outbound async producers | `jrag producers [--topic-contains …]` | `callees <producer>` |
+| Topics + consumers/producers | `jrag topics [--topic-contains …]` | — |
+| Cross-service seams of S | `jrag connection <S> [--inbound/--outbound/--both]` | — |
+| Who calls / what does M call? | `jrag callers <M>` / `jrag callees <M>` | `inspect` |
+| What routes does a controller expose? | `jrag callers <controller>` (folds in its `EXPOSES` routes) | `inspect` |
+| Who hits this route? | `jrag callers <route>` | — |
+| Implementations / subtypes of T? | `jrag implementations <T>` / `jrag subclasses <T>` | — |
+| Overriding / overridden methods? | `jrag overrides <method>` (UP) / `jrag overridden-by <method>` | — |
+| Who injects / depends on T? | `jrag dependencies <T>` / `jrag dependents <T>` | — |
+| Blast-radius of changing X? | `jrag impact <X>` (bounded fan-in) | `Grep` fallback |
+| Trace request flow A→B | `jrag flow <route-A>` | `connection <microservice>` (service's cross-service seams) |
+| File outline / imports | `jrag outline <file>` / `jrag imports <file>` | `inspect <row>` |
+| Find files by name/path | `Glob` | `Read` |
+| "Explain service S" | `jrag overview <service>` | `http-routes`/`http-clients`/`producers` |
+| "Explain route / topic" | `jrag overview <subject>` | `flow` |
+| Who changed X and when? | Bash: `git log`/`git blame` | — |
+| "How is this configured?" | `Glob` + `Grep`; `jrag search "<key>" --table yaml` | `Read` sections |
+
+**Escalation:** ① Most targeted tool first (identifier → `jrag inspect`; structural → matching `jrag` traversal; raw text / config / history → `Grep`/`Glob`/`Bash`). ② Fall back gracefully (`jrag` empty / `not_found` / exit 2 → `Grep`/`Glob`). ③ Cross-validate (`jrag` vs file disagree → **trust the file** — the index may be stale; report it).
+
+**Rules of thumb:** structure beats vector for exact questions (`jrag find`/`inspect` + traversal); vector beats structure for fuzzy discovery (`jrag search`); raw text / config / history beats both (`Grep`/`Glob`/`Bash`); file-system beats a stale index.
+
+---
+
+## Workflow Patterns
+
+- **"Explain feature X":** `jrag search "X"` → pick 1–3 hits → `jrag inspect <hit>` → targeted traversal (`callees`/`implementations`) → stop when answered.
+- **"Where is X used?":** `jrag inspect <X>` → `jrag callers <X>` + `jrag dependents <X>` → `Grep` the symbol name as fallback → report sites with file:line.
+- **"Find all Y":** structural → `jrag find --role <ROLE> [--service <S>]`; textual → `Grep`; broad → `Glob`+`Grep`. Summarize, don't dump.
+- **"Trace flow A→B":** `jrag flow <route-A>` → `jrag connection <microservice>` (cross-service seams) → `Grep` the gaps → report with file:line.
+- **"How is this configured?":** `Glob` `**/application*.yml` → `Grep` the key → `Read` sections → `jrag search "<key>" --table yaml`.
+- **"Orient in a new service":** `jrag overview <S>` → `jrag conventions --service <S>` → `jrag map --service <S>` → `jrag http-routes --service <S>`.
+
+## Recovery Playbook
+
+**After two failed attempts on the same intent, stop and report command, args, and result snippet.**
+
+| Symptom | Fix |
+| ------- | --- |
+| `status: error` "No index at …" | Run `java-codebase-rag init --source-root <root>`; retry |
+| `status: not_found` | `jrag search "<query>"`; or `find --fqn-contains …`; fallback `Grep` |
+| `many` candidates | Add `--kind`/`--role`/`--fqn-contains`/`--service`; re-run |
+| `find` too broad | Add `--service`, `--fqn-contains`, `--path-contains`, `--topic-contains` |
+| Empty `search` | Try `--table all`; `find --fqn-contains`; `Grep` |
+| `truncated: true` | Narrow, or page with `--offset` (`find`/`search` only) |
+| Empty across commands | Index missing/stale → `Grep`/`Glob`/`Read`; ask operator to rebuild (`java-codebase-rag reprocess`) |
+| CLI vs file disagree | **Trust the file**; report stale index |
+| `--offset` rejected | Only `find`/`search` accept it; others narrow via filters |
+| Wrong node picked | Resolve ambiguous — pass `--kind` |
+
+---
+
+## jrag surface — `--help` is the spec
+
+`jrag` is self-documenting and the canonical, always-fresh source for commands, flags, and valid enum values — so this skill doesn't duplicate them. Don't memorize the surface:
+
+- `jrag --help` — every command, grouped by intent, with one-line descriptions.
+- `jrag <command> --help` — that command's flags and accepted values. Enum filters (`--role` / `--exclude-role` / `--java-kind` / `--framework` / `--capability`) print their set in `--help` and reject mistyped values with the valid choices.
+
+The Decision Framework above tells you *which* command; reach for `--help` only when you need exact flags or enum values.
+
+**Prerequisite.** `jrag` needs an index — unindexed, every command exits 2 (`jrag status` checks; the file-system tools work without one).
+
+**Resolve-first contract.** Every `<query>` command resolves the identifier first, then maps `one` / `many` / `none` onto one envelope: `one` → run; `many` → return candidates and stop, **no silent guess across distinct types** (a class sharing its simple name with its own constructor still resolves to the type — narrow with `--kind` / `--role` / `--fqn-contains` / `--service`); `none` → `status: not_found` (exit 0), fall back to `search` or `Grep`. Pass names (FQN / simple name / route path / topic) or prior `sym:`/`route:`/`client:`/`producer:` ids — never raw node ids. `--kind` is a true resolve input; `--role` / `--java-kind` / `--fqn-contains` post-filter client-side.
+
+**Output.** Default is compact text; `--format json` emits `{status, nodes, edges, candidates, truncated, agent_next_actions, file_location}` (empty fields dropped; `file_location` is a `filename:line` string; `agent_next_actions` suggests ≤5 next commands). `truncated` pages via `--limit` / `--offset` (`find` / `search` only).
+
+**Edge semantics `--help` doesn't spell out.** `callers` / `callees` = `CALLS` in/out (on a controller/entry-point type, `callers` also lists the routes its methods `EXPOSE`). `impact` = bounded fan-in over `INJECTS` / `IMPLEMENTS` / `EXTENDS` (default depth 2; raise with `--depth`). `flow <route>` follows `EXPOSES` → `HTTP_CALLS` / `ASYNC_CALLS` → `CALLS`. `connection <microservice>` = inbound/outbound cross-service seams (its positional is a literal service name, not a query). Per-command edge mappings and the rest of the flag surface live in each command's `--help`.
+
+**Node id prefixes (from prior results):** `sym:` (Symbol), `route:`/`r:` (Route), `client:`/`c:` (Client), `producer:`/`p:` (Producer). **Symbol FQN:** `<package>.<Type>[.<NestedType>]#<methodName>(<SimpleType1>,…)` — generics erased, no spaces after commas, no-arg `()`, constructor `#<init>(...)`.
+
+**Ontology.** Role / symbol-kind / framework / capability values are enumerated in `--help`; client/producer kinds and source layers validate at runtime and surface the accepted set on a typo.

{java_codebase_rag-0.9.2 → java_codebase_rag-0.9.3}/java_codebase_rag/jrag.py

@@ -30,6 +30,7 @@ from pathlib import Path
 
 from java_codebase_rag._fdlimit import raise_fd_limit
 from java_codebase_rag._stdio import force_utf8_stdio
+from java_codebase_rag._version import version_string
 
 __all__ = ["build_parser", "main", "_console_script_main"]
 
@@ -302,6 +303,44 @@ def _preparse_render_flags(raw: list[str]) -> tuple[str | None, str | None, list
         return None, None, list(raw)
 
 
+# Closed enum taxonomies for the --role / --exclude-role / --java-kind /
+# --framework / --capability filters. Sourced from the canonical literals
+# (mcp_v2.Role, mcp_v2.DeclarationSymbolKind, mcp_v2.Framework) and
+# java_ontology.VALID_CAPABILITIES, and cross-checked by test_jrag_enum_choices.
+# Hardcoded here (not imported) so `jrag --help` stays fast — build_parser
+# imports no backend modules, and importing mcp_v2 costs ~0.7s.
+_ROLE_CHOICES = (
+    "CONTROLLER", "SERVICE", "REPOSITORY", "COMPONENT", "CONFIG",
+    "ENTITY", "CLIENT", "MAPPER", "DTO", "OTHER",
+)
+_JAVA_KIND_CHOICES = (
+    "class", "interface", "enum", "record", "annotation", "method", "constructor",
+)
+_FRAMEWORK_CHOICES = (
+    "spring_mvc", "webflux", "kafka", "rabbitmq", "jms", "stream", "feign",
+)
+_CAPABILITY_CHOICES = (
+    "MESSAGE_LISTENER", "MESSAGE_PRODUCER", "HTTP_CLIENT",
+    "SCHEDULED_TASK", "EXCEPTION_HANDLER",
+)
+
+
+def _upper_snake(value: str) -> str:
+    """Normalize a role/capability value to its stored UPPER_SNAKE form so
+    argparse ``choices=`` accepts flexible casing (``controller`` /
+    ``scheduled-task`` -> ``CONTROLLER`` / ``SCHEDULED_TASK``). Mirrors the
+    role/capability branch of jrag_envelope.normalize_enum."""
+    return value.strip().upper().replace("-", "_").replace(" ", "_")
+
+
+def _lower_snake(value: str) -> str:
+    """Normalize a java-kind/framework value to its stored lowercase form so
+    argparse ``choices=`` accepts flexible casing (``Spring-MVC`` ->
+    ``spring_mvc``). Mirrors the framework/java_kind branch of
+    jrag_envelope.normalize_enum."""
+    return value.strip().lower().replace("-", "_").replace(" ", "_")
+
+
 def build_parser() -> argparse.ArgumentParser:
     """Argparse builder. Imports no backend modules.
 
@@ -334,11 +373,16 @@ def build_parser() -> argparse.ArgumentParser:
         formatter_class=argparse.RawDescriptionHelpFormatter,
         exit_on_error=False,
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=version_string(parser.prog),
+    )
     subparsers = parser.add_subparsers(dest="command", parser_class=_EnvelopeArgumentParser)
 
     # Common flags applied per command via parents=[_common_parser()]. NOT
-    # global so commands can override defaults (e.g. fan-out commands use
-    # limit=10). The helper builds a FRESH parser each call so every subparser
+    # global so commands can override defaults (e.g. inspect/orientation
+    # default --detail to full). The helper builds a FRESH parser each call so every subparser
     # owns its own --detail Action object — argparse `parents` shares Action
     # objects by reference, and `set_defaults(detail=...)` mutates the shared
     # action's default (CPython walks `self._actions`), so a single shared
@@ -360,7 +404,7 @@ def build_parser() -> argparse.ArgumentParser:
             ),
         )
         common.add_argument(
-            "--limit", type=int, default=20, help="Cap on results (default 20; 10 for fan-out)."
+            "--limit", type=int, default=20, help="Cap on results (default 20)."
         )
         common.add_argument(
             "--index-dir",
@@ -455,12 +499,12 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Node kind (omit for auto-inference from domain flags).",
     )
-    find.add_argument("--role", type=str, default=None, help="Filter by role.")
-    find.add_argument("--exclude-role", type=str, default=None, help="Exclude by role.")
-    find.add_argument("--java-kind", type=str, default=None, help="Filter by Java symbol kind.")
+    find.add_argument("--role", type=_upper_snake, choices=_ROLE_CHOICES, default=None, help="Filter by role.")
+    find.add_argument("--exclude-role", type=_upper_snake, choices=_ROLE_CHOICES, default=None, help="Exclude by role.")
+    find.add_argument("--java-kind", type=_lower_snake, choices=_JAVA_KIND_CHOICES, default=None, help="Filter by Java symbol kind.")
     find.add_argument("--annotation", type=str, default=None, help="Filter by annotation.")
-    find.add_argument("--capability", type=str, default=None, help="Filter by capability.")
-    find.add_argument("--framework", type=str, default=None, help="Filter by framework.")
+    find.add_argument("--capability", type=_upper_snake, choices=_CAPABILITY_CHOICES, default=None, help="Filter by capability.")
+    find.add_argument("--framework", type=_lower_snake, choices=_FRAMEWORK_CHOICES, default=None, help="Filter by framework.")
     find.add_argument("--source-layer", type=str, default=None, help="Filter by source layer.")
     find.add_argument("--fqn-contains", type=str, default=None, help="Filter by FQN substring.")
     find.add_argument("--http-method", type=str, default=None, help="Filter by HTTP method (route).")
@@ -496,8 +540,8 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Hint for resolve (omitted for broad search).",
     )
-    inspect.add_argument("--java-kind", type=str, default=None, help="Post-filter by Java symbol kind.")
-    inspect.add_argument("--role", type=str, default=None, help="Post-filter by role.")
+    inspect.add_argument("--java-kind", type=_lower_snake, choices=_JAVA_KIND_CHOICES, default=None, help="Post-filter by Java symbol kind.")
+    inspect.add_argument("--role", type=_upper_snake, choices=_ROLE_CHOICES, default=None, help="Post-filter by role.")
     inspect.add_argument("--fqn-contains", type=str, default=None, help="Post-filter by FQN substring.")
     inspect.set_defaults(handler=_cmd_inspect, detail="full")
 
@@ -512,7 +556,7 @@ def build_parser() -> argparse.ArgumentParser:
             "kafka topics live under `topics`."
         ),
     )
-    http_routes.add_argument("--framework", type=str, default=None, help="Filter by framework.")
+    http_routes.add_argument("--framework", type=_lower_snake, choices=_FRAMEWORK_CHOICES, default=None, help="Filter by framework.")
     http_routes.add_argument("--path-contains", type=str, default=None, help="Filter by path substring.")
     http_routes.add_argument("--method", type=str, default=None, help="Filter by HTTP method.")
     http_routes.set_defaults(handler=_cmd_routes, detail="full", auto_scope=True)
@@ -611,8 +655,8 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Hint for resolve (omit for broad search).",
     )
-    resolve_parent.add_argument("--java-kind", type=str, default=None, help="Post-filter by Java symbol kind.")
-    resolve_parent.add_argument("--role", type=str, default=None, help="Post-filter by role.")
+    resolve_parent.add_argument("--java-kind", type=_lower_snake, choices=_JAVA_KIND_CHOICES, default=None, help="Post-filter by Java symbol kind.")
+    resolve_parent.add_argument("--role", type=_upper_snake, choices=_ROLE_CHOICES, default=None, help="Post-filter by role.")
     resolve_parent.add_argument("--fqn-contains", type=str, default=None, help="Post-filter by FQN substring.")
 
     callers = subparsers.add_parser(
@@ -694,7 +738,7 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     implementations.add_argument("query", help="Interface FQN or name.")
-    implementations.add_argument("--capability", type=str, default=None, help="Filter implementors by capability.")
+    implementations.add_argument("--capability", type=_upper_snake, choices=_CAPABILITY_CHOICES, default=None, help="Filter implementors by capability.")
     implementations.set_defaults(handler=_cmd_implementations, auto_scope=True)
 
     subclasses = subparsers.add_parser(
@@ -777,16 +821,21 @@ def build_parser() -> argparse.ArgumentParser:
     decompose.add_argument("--depth", type=int, default=2, help="Neighbour hop count per stage (clamped 1..3, default 2).")
     decompose.add_argument(
         "--follow-calls",
-        action="store_true",
+        action=argparse.BooleanOptionalAction,
+        default=True,
         dest="follow_calls",
-        help="Follow DECLARES+CALLS type-to-type hops to top up each stage.",
+        help=(
+            "Top up each stage with DECLARES+CALLS type-to-type hops when the "
+            "structural INJECTS/EXTENDS/IMPLEMENTS pass under-fills it (default: "
+            "on). --no-follow-calls restricts the waterfall to structural edges."
+        ),
     )
     decompose.add_argument(
-        "--max-stage",
+        "--per-stage-limit",
         type=int,
         default=20,
-        dest="max_stage",
-        help="Cap on symbols per stage (stage_limit, default 20).",
+        dest="per_stage_limit",
+        help="Cap on symbols per stage (stage_limit, default 20). Not a stage-count knob.",
     )
     decompose.add_argument(
         "--min-confidence",
@@ -1094,12 +1143,12 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     # NodeFilter flags (same set as `find` filter mode, minus the query-only ones).
-    search.add_argument("--role", type=str, default=None, help="Filter by role.")
-    search.add_argument("--exclude-role", type=str, default=None, dest="exclude_role", help="Exclude by role.")
-    search.add_argument("--java-kind", type=str, default=None, dest="java_kind", help="Filter by Java symbol kind.")
+    search.add_argument("--role", type=_upper_snake, choices=_ROLE_CHOICES, default=None, help="Filter by role.")
+    search.add_argument("--exclude-role", type=_upper_snake, choices=_ROLE_CHOICES, default=None, dest="exclude_role", help="Exclude by role.")
+    search.add_argument("--java-kind", type=_lower_snake, choices=_JAVA_KIND_CHOICES, default=None, dest="java_kind", help="Filter by Java symbol kind.")
     search.add_argument("--annotation", type=str, default=None, help="Filter by annotation.")
-    search.add_argument("--capability", type=str, default=None, help="Filter by capability.")
-    search.add_argument("--framework", type=str, default=None, help="Filter by framework.")
+    search.add_argument("--capability", type=_upper_snake, choices=_CAPABILITY_CHOICES, default=None, help="Filter by capability.")
+    search.add_argument("--framework", type=_lower_snake, choices=_FRAMEWORK_CHOICES, default=None, help="Filter by framework.")
     search.add_argument("--fqn-contains", type=str, default=None, dest="fqn_contains", help="Filter by FQN substring.")
     search.add_argument(
         "--offset",
@@ -2404,6 +2453,44 @@ def _cmd_callers(args: argparse.Namespace) -> int:
         edges.append(
             {"other_id": ce.src.id, "edge_type": "CALLS", "confidence": ce.confidence}
         )
+    # Entry-point awareness. A controller / messaging-listener type is invoked
+    # via the routes its methods EXPOSE (Controller -[:DECLARES]-> method
+    # -[:EXPOSES]-> Route), NOT via in-repo CALLS edges — so find_callers is
+    # typically empty for HTTP handlers. Without this fold, `callers
+    # <Controller>` returns a bug-looking empty list when the controller is the
+    # very thing the agent is investigating. The routes ARE its inbound callers,
+    # so surface them as additional EXPOSES rows alongside any CALLS-in edges.
+    # Gated on having DECLARES.EXPOSES out-edges (covers any entry-point holder,
+    # not just role=CONTROLLER). Routes are additive and usually few, so they do
+    # not count against the CALLS --limit (cf. the callees client/producer path,
+    # which likewise emits its own targets without sharing the CALLS budget).
+    expose_rows = graph._rows(  # noqa: SLF001 - one-shot aggregation, cf. _cmd_callees client path
+        "MATCH (t:Symbol {id: $tid})-[:DECLARES]->(m:Symbol)-[e:EXPOSES]->(r:Route) "
+        "RETURN r.id AS rid, r.method AS rmethod, r.path AS rpath, "
+        "r.path_template AS rpt, r.microservice AS rms, "
+        "m.fqn AS via_fqn, e.confidence AS conf",
+        {"tid": root_id},
+    )
+    for row in expose_rows:
+        rid = str(row.get("rid") or "")
+        if not rid or rid in nodes:
+            continue
+        rmethod = str(row.get("rmethod") or "")
+        rpath = str(row.get("rpt") or row.get("rpath") or "")
+        nodes[rid] = {
+            "id": rid,
+            "kind": "route",
+            "fqn": f"{rmethod} {rpath}".strip(),
+            "method": rmethod,
+            "path": rpath,
+            "microservice": str(row.get("rms") or ""),
+        }
+        edge_row: dict = {"other_id": rid, "edge_type": "EXPOSES"}
+        via_fqn = str(row.get("via_fqn") or "")
+        if via_fqn:
+            # Declaring method that exposes the route; rendered at --detail full.
+            edge_row["from_fqn"] = via_fqn
+        edges.append(edge_row)
     nodes[root_id] = root_dict
     return _emit_traversal(
         args, root_id=root_id, nodes=nodes, edges=edges,
@@ -2956,8 +3043,8 @@ def _cmd_decompose(args: argparse.Namespace) -> int:
     stages = graph.trace_flow(
         seed_fqns=[seed_fqn],
         depth=depth,
-        follow_calls=getattr(args, "follow_calls", False),
-        stage_limit=getattr(args, "max_stage", 20),
+        follow_calls=getattr(args, "follow_calls", True),
+        stage_limit=getattr(args, "per_stage_limit", 20),
         min_call_confidence=getattr(args, "min_confidence", 0.0),
         exclude_external=not getattr(args, "include_external", False),
         microservice=args.service,
@@ -2983,12 +3070,12 @@ def _cmd_decompose(args: argparse.Namespace) -> int:
                 edge_row["from_fqn"] = via.from_fqn
             edges.append(edge_row)
     # --limit is inherited from common but does not cap decompose (trace_flow
-    # is stage-limited via --max-stage, not a total edge count). Warn when the
+    # is stage-limited via --per-stage-limit, not a total edge count). Warn when the
     # user explicitly set --limit away from the default so they get a signal
     # rather than a silent multi-stage dump (Fix 4).
     if args.limit is not None and args.limit != 20:
         warnings.append(
-            "--limit does not apply to decompose; use --max-stage to cap per-stage breadth"
+            "--limit does not apply to decompose; use --per-stage-limit to cap per-stage breadth"
         )
     return _emit_traversal(
         args, root_id=root_id, nodes=nodes, edges=edges,

{java_codebase_rag-0.9.2 → java_codebase_rag-0.9.3}/java_codebase_rag/jrag_render.py

@@ -472,11 +472,19 @@ def _render_traversal(envelope: Envelope, *, noun: str, detail: str = "normal")
             by_stage[s].append(e)
         for s in stage_order:
             stage_edges = by_stage[s]
-            roles = {str(e.get("role") or "").upper() for e in stage_edges if e.get("role")}
+            # Preserve first-seen order so a mixed stage reads naturally
+            # (e.g. `stage 1 (service, component):`) instead of dropping the
+            # role label entirely — the role allow-list is the whole point of a
+            # role-waterfall, so hiding it on the busiest stages is a loss.
+            seen: list[str] = []
+            for e in stage_edges:
+                r = str(e.get("role") or "").strip().lower()
+                if r and r not in seen:
+                    seen.append(r)
             if s == 0:
                 header = "stage 0 (seed):"
-            elif len(roles) == 1:
-                header = f"stage {s} ({next(iter(roles)).lower()}):"
+            elif seen:
+                header = f"stage {s} ({', '.join(seen)}):"
             else:
                 header = f"stage {s}:"
             lines.append(header)

{java_codebase_rag-0.9.2 → java_codebase_rag-0.9.3/java_codebase_rag.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.9.2
+Version: 0.9.3
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -168,6 +168,7 @@ jrag entities                  # JPA entities
 
 # Traversals (all resolve-first)
 jrag callers ChatService#assign(Request)   # who calls me?
+jrag callers ChatIngressController         # controller: also lists its EXPOSES routes
 jrag callees ChatService#assign(Request)   # what do I call?
 jrag hierarchy AbstractBase               # type tree (parents + children)
 jrag implementations PaymentProcessor     # classes implementing an interface

{java_codebase_rag-0.9.2 → java_codebase_rag-0.9.3}/java_codebase_rag.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ server.py
 java_codebase_rag/__init__.py
 java_codebase_rag/_fdlimit.py
 java_codebase_rag/_stdio.py
+java_codebase_rag/_version.py
 java_codebase_rag/cli.py
 java_codebase_rag/cli_format.py
 java_codebase_rag/cli_progress.py
@@ -79,6 +80,7 @@ tests/test_installer_integration.py
 tests/test_installer_surface.py
 tests/test_java_codebase_rag_cli.py
 tests/test_jrag_auto_scope.py
+tests/test_jrag_enum_choices.py
 tests/test_jrag_envelope.py
 tests/test_jrag_listing.py
 tests/test_jrag_locate.py
@@ -111,4 +113,5 @@ tests/test_schema_consistency.py
 tests/test_search_lancedb.py
 tests/test_search_lancedb_capability.py
 tests/test_string_value_atoms.py
-tests/test_vectors_progress.py
+tests/test_vectors_progress.py
+tests/test_version_flag.py

{java_codebase_rag-0.9.2 → java_codebase_rag-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "java-codebase-rag"
-version = "0.9.2"
+version = "0.9.3"
 description = "MCP server for semantic + structural search over Java codebases"
 readme = "README.md"
 requires-python = ">=3.11"