PyPI - java-codebase-rag - Versions diffs - 0.9.2__py3-none-any.whl → 0.9.4__py3-none-any.whl - Mend

java-codebase-rag 0.9.2py3-none-any.whl → 0.9.4py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

java_codebase_rag/_version.py ADDED Viewed

@@ -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/cli.py CHANGED Viewed

@@ -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/install_data/agents/explorer-rag-cli.md CHANGED Viewed

@@ -1,125 +1,70 @@
 ---
 name: explorer-rag-cli
-description: "MUST BE USED PROACTIVELY. Universal read-only explorer agent that drives the `jrag` CLI for graph-native codebase navigation (callers, callees, routes, clients, producers, impact, search, inspect, flow, overview) and falls back to file-system search (grep, glob, file 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. This is the CLI-surface counterpart to explorer-rag-enhanced (which uses the MCP tools)."
+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 drives the **`jrag` CLI** (the agent-facing shell surface of java-codebase-rag) and falls back to **broad file-system search** (grep, glob, file reading) when the index is missing or stale.
+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. **Names in, names out.** Every `<query>` is human-readable (FQN / simple name / route path / topic). Raw node IDs are never required — `jrag` resolves internally.
-3. **One command per intent.** `jrag` collapses resolve + walk into one call. Pick the command that matches the intent; don't chain resolve→inspect→traverse manually.
-4. **Smallest sufficient tool.** Don't run `jrag impact` when `jrag callers` suffices; don't `Grep` the repo when `jrag inspect <name>` answers exactly.
-5. **Excerpts over dumps.** Read excerpts and relevant sections, not entire files. Summarize findings.
-6. **Stop when answered.** Don't prefetch unrelated subgraphs or scan unrelated directories.
-You are the **CLI-surface** explorer — use `jrag` shell commands, **not** the MCP tools. One surface per project; the MCP counterpart is `explorer-rag-enhanced`.
-## Prerequisite: index must exist
+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.
-`jrag` is a thin layer over the existing index. If unindexed, every command exits 2 with an actionable envelope. Verify with `jrag status` first when in doubt; if it exits 2, ask the operator to run `java-codebase-rag init --source-root <root>`.
+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
-### `jrag` command groups
-Run `jrag --help` for the canonical list.
-| Group | Commands |
-| --- | --- |
-| **Orientation** | `status`, `microservices`, `map`, `conventions`, `overview` |
-| **Locate** | `find`, `search` |
-| **Listings** | `http-routes`, `http-clients`, `producers`, `topics`, `jobs`, `listeners`, `entities` |
-| **Traversal** | `callers`, `callees`, `hierarchy`, `implementations`, `subclasses`, `overrides`, `overridden-by`, `dependents`, `impact`, `flow`, `decompose`, `dependencies`, `connection` |
-| **Inspection** | `inspect`, `outline`, `imports` |
-### Common flags
-```
---service <name>            Filter by microservice
---module <name>             Filter by module
---limit <N>                 Cap on results (default 20; 10 for fan-out)
---format text|json          Output format (default: text)
---detail brief|normal|full  How much of each node/edge is shown (default: normal);
-                            orthogonal to --format. brief=name @service;
-                            normal=+module/role/file/score; full=+signature/
-                            annotations/snippet. inspect + orientation default to full.
---index-dir <path>          Index directory override
-```
-`--offset` is supported **only** on `find`/`search`; others emit `truncated: more results — narrow your query` when capped.
-### File-system tools
-`Grep` (contents), `Glob` (name/path patterns), `Read` (`offset`/`limit`). Plus `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`/`WebFetch`.
+- **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
-| Question type | Primary approach |
-| --- | --- |
-| "Who calls method M?" / "What does M call?" | `jrag callers <M>` / `jrag callees <M>` |
-| "Where is class X?" | `jrag inspect <X>`; fallback `Grep`/`Glob` |
-| "All controllers in service S" | `jrag find --role CONTROLLER --service S` |
-| "Routes/endpoints in service S" | `jrag http-routes --service S` |
-| "Who implements interface T?" / "Where injected?" | `jrag implementations <T>` / `jrag dependencies <T>` |
-| "Who depends on T?" | `jrag dependents <T>` |
-| "Impact of changing X?" | `jrag impact <X>` (bounded fan-in) |
-| "Trace request flow A→B" | `jrag flow <route-A>` → `jrag connection A B` |
-| "Orient in service S" | `jrag overview <S>` |
-| Find files / text | `Glob` / `Grep` |
-| Read config/build/test files | `Read` |
-| Who changed this and when? | Bash: `git log` / `git blame` |
-| "How is this concept used?" | `jrag search "<text>"` (fuzzy) + `Grep` (text) |
-| NL "find X" | `jrag search "<X>"` → `jrag inspect <hit>` |
-**Escalation:** ① Most targeted command first (identifier → `jrag inspect <X>`; structural → matching traversal). ② Fall back gracefully (`jrag` empty/`not_found` → `Grep`/`Glob`). ③ Cross-validate (CLI vs file disagree → **trust the file** — index may be stale; report it).
+| 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).
 ---
-## Resolve-first contract (every `<query>` command)
-Every `jrag` command that takes a `<query>` runs `resolve_v2` internally:
-| `resolve_v2` status | Behavior / action |
-| --- | --- |
-| `one` | Run the traversal/listing against the resolved node. Read the result. |
-| `many` | Return candidates and stop. **No auto-pick.** Disambiguate with `--kind`/`--role`/`--fqn-contains`/`--service`; re-run. |
-| `none` | `status: not_found` envelope (exit 0). Fall back to `jrag search` or `Grep`. |
-Never look up a raw node ID — pass an FQN, simple name, prior `sym:`/`route:`/`client:`/`producer:` id, route path, or topic. Only `--kind` is a true resolve input; `--role`/`--java-kind`/`--fqn-contains` post-filter client-side, while `--service`/`--module` are resolve-time filters on `inspect`/`callers` and result filters elsewhere.
-## Output envelope
-`--format` (text|json) picks the representation; `--detail` (brief|normal|full) picks how much of each node/edge shows — **both honor the same detail level**. Default: `text` + `normal`. `inspect` and orientation commands default to `full`. `--format json` emits the projected envelope (empty fields dropped): `status`, `nodes`, `edges`, `candidates`, `truncated`, `agent_next_actions` (≤5, a starting point not a directive), `file_location` (only on `one`-hit resolve). `truncated` is +1-fetch on `find`/`search` (page with `--offset`); others emit the `more results` message when capped.
-## Traversal direction reference
-`jrag` abstracts away `direction`/`edge_types`:
-| Intent (command) | Underlying edges |
-| --- | --- |
-| `callers` / `callees` | `CALLS` in / out |
-| `hierarchy` | `EXTENDS` + `IMPLEMENTS`, both directions (parents + children) |
-| `implementations` / `subclasses` | `IMPLEMENTS` / `EXTENDS` in |
-| `overrides` / `overridden-by` | `OVERRIDES` out (subtype→supertype) / in |
-| `dependencies` / `dependents` | `INJECTS` out / in |
-| `impact` | bounded fan-in: `INJECTS`/`IMPLEMENTS`/`EXTENDS` in (depth ≤2) |
-| `flow <route>` | `EXPOSES`/`HTTP_CALLS`/`ASYNC_CALLS`/`CALLS` |
-| `connection A B` | bounded search over the same edge set |
-**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 glossary
-**Roles:** `CONTROLLER` (HTTP/messaging entry) | `SERVICE` (business logic) | `REPOSITORY` (data access) | `COMPONENT` (Spring component) | `CONFIG` (`@Configuration`) | `ENTITY` (JPA/persistence) | `CLIENT` (outbound wrapper) | `MAPPER` (converter) | `DTO` | `OTHER` (infra/utility).
-**Capabilities:** `MESSAGE_LISTENER`, `MESSAGE_PRODUCER`, `HTTP_CLIENT`, `SCHEDULED_TASK`, `EXCEPTION_HANDLER`.
-**Symbol kinds:** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
-**Route frameworks:** `spring_mvc`/`webflux` (HTTP), `kafka`/`rabbitmq`/`jms`/`stream` (messaging), `feign` (client mirrors). Route *kinds*: `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:** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
+## 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
@@ -139,10 +84,23 @@ Never look up a raw node ID — pass an FQN, simple name, prior `sym:`/`route:`/
 ---
-## Workflow Patterns
+## jrag surface — `--help` is the spec
-- **"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` 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 A B` → `Grep` 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>`.
+`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/install_data/skills/explore-codebase-cli/SKILL.md CHANGED Viewed

@@ -1,158 +1,68 @@
 ---
 name: explore-codebase-cli
-description: "MUST BE USED PROACTIVELY. Universal read-only codebase exploration via the `jrag` CLI — one command per engineering intent (callers, callees, routes, clients, producers, impact, search, inspect, flow, overview). Use for any exploration: locating code, tracing dependencies, finding patterns, 'where is X', 'who calls Y', 'find all controllers', 'trace the flow from A to B'. Combines graph navigation with file-system search (grep, glob, file reading). Do NOT use when the answer is already in open context or for a single known file — read that file directly."
+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."
 ---
-# /explore-codebase-cli — Universal codebase exploration via `jrag`
-Read-only exploration combining **graph navigation through the `jrag` CLI** with **broad file-system search**. `jrag` loads the same index as the MCP server but exposes one shell command per intent instead of five MCP tools.
-Use any time you must search, locate, navigate, or explore. **Do NOT use when** the answer is already in context or for a single known file — read it directly.
 ## Core Principles
-1. **Read-only.** Never edit, write, or modify any file.
-2. **Names in, names out.** Every `<query>` is human-readable (FQN / simple name / route path / topic). Raw node IDs never required.
-3. **One command per intent.** `jrag` collapses resolve + walk into one call — don't chain resolve→describe→neighbors manually.
-4. **Stop when answered.** Don't prefetch unrelated subgraphs or directories.
-**One surface per project.** This is the CLI surface; the MCP surface (`search`/`find`/`describe`/`neighbors`/`resolve`) is mutually exclusive — running both strands the agent in two vocabularies.
-## Prerequisite: index must exist
-`jrag` is a thin layer over the existing index. If unindexed, every command exits 2:
-```
-status: error
-message: No index at <path>. Run: java-codebase-rag init --source-root <root>
-```
-Verify with `jrag status` when in doubt.
+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
-### `jrag` command groups
-Run `jrag --help` for the canonical list.
-| Group | Commands |
-| --- | --- |
-| **Orientation** | `status`, `microservices`, `map`, `conventions`, `overview` |
-| **Locate** | `find`, `search` |
-| **Listings** | `http-routes`, `http-clients`, `producers`, `topics`, `jobs`, `listeners`, `entities` |
-| **Traversal** | `callers`, `callees`, `hierarchy`, `implementations`, `subclasses`, `overrides`, `overridden-by`, `dependents`, `impact`, `flow`, `decompose`, `dependencies`, `connection` |
-| **Inspection** | `inspect`, `outline`, `imports` |
-### Common flags
-```
---service <name>            Filter by microservice
---module <name>             Filter by module
---limit <N>                 Cap on results (default 20; 10 for fan-out)
---format text|json          Output format (default: text)
---detail brief|normal|full  How much of each node/edge is shown (default: normal);
-                            orthogonal to --format. brief=name @service;
-                            normal=+module/role/file/score; full=+signature/
-                            annotations/snippet. inspect + orientation default to full.
---index-dir <path>          Index directory override (default: discovered from cwd)
-```
+- **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`.
-`--offset` is supported **only** on `find` and `search`. Other commands emit `truncated: more results — narrow your query` when capped.
-### File-system tools
-`Grep` (content/regex), `Glob` (name/path patterns), `Read` (`offset`/`limit`). Plus `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 `jrag` command | Follow-up |
-| ---------- | -------------------- | --------- |
+| 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>` | `connection <A> <B>` |
+| 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` |
-| Find files / text | `Glob` / `Grep` | `Read` |
+| "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 command first → ② fall back gracefully (`callers` empty → `Grep`) → ③ cross-validate (CLI vs file disagree → **trust the file** — index may be stale).
+**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 (`find`/`inspect` + traversal); vector beats structure for fuzzy discovery (`search`); file-system beats stale index.
+**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.
 ---
-## Resolve-first contract (every `<query>` command)
-Every `jrag` command that takes a `<query>` runs `resolve_v2` internally:
-| `resolve_v2` status | `jrag` behavior |
-| --- | --- |
-| `one` | Run the traversal/listing against the resolved node. |
-| `many` | Return the candidate list and stop. **No auto-pick.** Disambiguate with `--kind`/`--role`/`--fqn-contains`/`--service`; re-run. |
-| `none` | `status: not_found` envelope (exit 0). Fall back to `search` or `Grep`. |
-Never look up a raw node ID — pass an FQN, simple name, prior `sym:`/`route:`/`client:`/`producer:` id, route path, or topic. Only `--kind` is a true resolve input; `--role`/`--java-kind`/`--fqn-contains` post-filter client-side, while `--service`/`--module` are resolve-time filters on `inspect`/`callers` and result filters elsewhere.
-## Output envelope
-`--format` (text|json) picks the representation; `--detail` (brief|normal|full) picks how much of each node/edge shows — **both honor the same detail level**. Default: `text` + `normal`. `inspect` and orientation commands default to `full`. `--format json` emits the projected envelope (empty fields dropped):
-```json
-{
-  "status": "ok|not_found|error",
-  "nodes": {"<id>": {...}},
-  "edges": [{...}],
-  "candidates": [{...}],
-  "truncated": false,
-  "agent_next_actions": ["jrag callers <id>", "..."],
-  "file_location": {"filename": "...", "start_line": 123}
-}
-```
-`truncated` is computed via +1-fetch on `find`/`search` (use `--limit`, then `--offset`); other commands emit the `more results` message when capped. `agent_next_actions` (≤5) maps result edges to next commands — a starting point, not a directive. `file_location` populates only on `one`-hit resolve.
-## Traversal direction reference
-`jrag` abstracts away `direction`/`edge_types` — you name the intent, it picks the edges:
-| Intent (command) | Underlying edges |
-| --- | --- |
-| `callers` / `callees` | `CALLS` in / out |
-| `hierarchy` | `EXTENDS` + `IMPLEMENTS`, both directions (parents + children) |
-| `implementations` / `subclasses` | `IMPLEMENTS` / `EXTENDS` in |
-| `overrides` / `overridden-by` | `OVERRIDES` out (subtype→supertype) / in |
-| `dependencies` / `dependents` | `INJECTS` out / in |
-| `impact` | bounded fan-in: `INJECTS`/`IMPLEMENTS`/`EXTENDS` in (depth ≤2) |
-| `flow <route>` | `EXPOSES`/`HTTP_CALLS`/`ASYNC_CALLS`/`CALLS` |
-| `connection A B` | bounded search over the same edge set |
-**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 glossary
-**Roles:** `CONTROLLER` | `SERVICE` | `REPOSITORY` | `COMPONENT` | `CONFIG` | `ENTITY` | `CLIENT` | `MAPPER` | `DTO` | `OTHER`.
-**Capabilities:** `MESSAGE_LISTENER`, `MESSAGE_PRODUCER`, `HTTP_CLIENT`, `SCHEDULED_TASK`, `EXCEPTION_HANDLER`.
-**Symbol kinds:** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
-**Route frameworks:** `spring_mvc`/`webflux` (HTTP), `kafka`/`rabbitmq`/`jms`/`stream` (messaging), `feign` (client mirrors). Route *kinds*: `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:** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
+## 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
@@ -173,11 +83,23 @@ Never look up a raw node ID — pass an FQN, simple name, prior `sym:`/`route:`/
 ---
-## Workflow Patterns
+## jrag surface — `--help` is the spec
-- **"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` 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 A B` → `Grep` 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>`.
+`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/jrag.py CHANGED Viewed

@@ -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/jrag_render.py CHANGED Viewed

@@ -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.dist-info → java_codebase_rag-0.9.4.dist-info}/METADATA RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.9.2
+Version: 0.9.4
 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.dist-info → java_codebase_rag-0.9.4.dist-info}/RECORD RENAMED Viewed

@@ -19,25 +19,26 @@ server.py,sha256=nOK3DOr-i3PJnVmE7neye_tptJumgXfIXPlTIn01MPQ,37065
 java_codebase_rag/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 java_codebase_rag/_fdlimit.py,sha256=vkwjsPbZfxzZ2DZTPWO5DxtuNlLzOADzIq07iYX7GCU,2465
 java_codebase_rag/_stdio.py,sha256=TDNbpt2EP0_Zd622ihdlKwlMfxkKHWOfgLVcU6TcNbo,1458
-java_codebase_rag/cli.py,sha256=8WKk-_Zl1Sp7wHX4Y5f3bkIy8hHRH_QWrNuX_3WYTm4,45269
+java_codebase_rag/_version.py,sha256=Dnoh_a-c13fqPQ-HV9CsSPbFUkihUJl_z5CACW4qDyA,1365
+java_codebase_rag/cli.py,sha256=nI3eQ_21YDA80WbbYxKEVpIl9uA9tsf1szQhz_C-t9Q,45446
 java_codebase_rag/cli_format.py,sha256=CT7-xdwZ0bMCdP68_UOwkvm-mnLluU3LutlM-mDNk60,1839
 java_codebase_rag/cli_progress.py,sha256=q6Wh97yzLGs1B8UFk_WAKivfQu7Y5RnUUE-T2YHWkIs,3237
 java_codebase_rag/config.py,sha256=1EAlKtQx7LUo-gPoE6BOVLz0YEl1OpWFRABkF06zjgk,26464
 java_codebase_rag/installer.py,sha256=c-_tR1Ct_O3yhmruFRnDoM1Wilz-igD9qdkDPsNqLMI,79934
-java_codebase_rag/jrag.py,sha256=KYv1pD_FTdYh0NqEwO_yzqgHiv5PDFcMiL26aA40QwI,192278
+java_codebase_rag/jrag.py,sha256=odwSSxnWUOeyhx3O-C_q0y3D4KOVtqUqeDMyKgDVqNc,196991
 java_codebase_rag/jrag_envelope.py,sha256=5jD3p2O-p9acAKHqoif5FFoqgP7Q2ziCuKSiPCHoywc,47505
 java_codebase_rag/jrag_hints.py,sha256=k2PFE4s3lZgBYHMdZcTjx1-w28nfQcBtQEVsSxI_DvE,9262
-java_codebase_rag/jrag_render.py,sha256=1nUyamL-MOOXDlKvssp-LsBgEtznUnGj_cPteSwuS90,31953
+java_codebase_rag/jrag_render.py,sha256=WrBtVFvhpVlykHXg-uZtbdv2XsCw4KXNXVarE06pkLk,32350
 java_codebase_rag/lance_optimize.py,sha256=HI3aFebP1fenLL6Cav1jMG5kLXSrHLndO_MIJY6qQVo,11977
 java_codebase_rag/pipeline.py,sha256=L65mjK-IxkVWazUNVyIvzfQNi24behQu-Kdc7o_HwEk,17754
 java_codebase_rag/progress.py,sha256=2IxdMALDM0wAQCyJrrfZ975zM_85C-4BfHxf4AtYifE,23212
-java_codebase_rag/install_data/agents/explorer-rag-cli.md,sha256=mMij_BIQM4agaYhGVYjC-fQSe3We1HFeBvc5JBjJj6A,10071
+java_codebase_rag/install_data/agents/explorer-rag-cli.md,sha256=bVmmzrBSSamMz7hDIKxL5alAZOXsJ_Km8TQnCcxDad0,10292
 java_codebase_rag/install_data/agents/explorer-rag-enhanced.md,sha256=gZsNFbuK0lSnOIlplbbS_muz2ozokJqvFUv65QM0NDM,10406
 java_codebase_rag/install_data/skills/explore-codebase/SKILL.md,sha256=A-v2dueVnxwBzBlxoRjZ2zOJk8DranLQ1TElwn94h0s,11529
-java_codebase_rag/install_data/skills/explore-codebase-cli/SKILL.md,sha256=V5gIKKGkgk2KlAFf9JqPareQDMt1iQOI7cwhfOqJL1c,11348
-java_codebase_rag-0.9.2.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
-java_codebase_rag-0.9.2.dist-info/METADATA,sha256=3lfDnbvPb-vpc_81VLNobOgdUKncX6ejy3TDUUSj4Vo,20088
-java_codebase_rag-0.9.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-java_codebase_rag-0.9.2.dist-info/entry_points.txt,sha256=cj3QTc11UYVQnj9T3orc4daiIGaCYrXP149vKbH2R4U,168
-java_codebase_rag-0.9.2.dist-info/top_level.txt,sha256=8vC-VN3cMwz5vhkSTaeJ1a1bDeqLWEfrTks1CvEvIg0,273
-java_codebase_rag-0.9.2.dist-info/RECORD,,
+java_codebase_rag/install_data/skills/explore-codebase-cli/SKILL.md,sha256=K2qwZqk2xPxjPxXtUHvax1Ug2J7nBYeMTIjRznO100g,10059
+java_codebase_rag-0.9.4.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
+java_codebase_rag-0.9.4.dist-info/METADATA,sha256=CEq0X_nWAQP89qo0VJgX5QR3Pf9NcsaRnk-AruJkL6k,20175
+java_codebase_rag-0.9.4.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+java_codebase_rag-0.9.4.dist-info/entry_points.txt,sha256=cj3QTc11UYVQnj9T3orc4daiIGaCYrXP149vKbH2R4U,168
+java_codebase_rag-0.9.4.dist-info/top_level.txt,sha256=8vC-VN3cMwz5vhkSTaeJ1a1bDeqLWEfrTks1CvEvIg0,273
+java_codebase_rag-0.9.4.dist-info/RECORD,,

{java_codebase_rag-0.9.2.dist-info → java_codebase_rag-0.9.4.dist-info}/WHEEL RENAMED Viewed

File without changes

{java_codebase_rag-0.9.2.dist-info → java_codebase_rag-0.9.4.dist-info}/entry_points.txt RENAMED Viewed

File without changes

{java_codebase_rag-0.9.2.dist-info → java_codebase_rag-0.9.4.dist-info}/licenses/LICENSE RENAMED Viewed

File without changes

{java_codebase_rag-0.9.2.dist-info → java_codebase_rag-0.9.4.dist-info}/top_level.txt RENAMED Viewed

File without changes

java-codebase-rag 0.9.2__py3-none-any.whl → 0.9.4__py3-none-any.whl

java-codebase-rag 0.9.2py3-none-any.whl → 0.9.4py3-none-any.whl