java-codebase-rag 0.12.0__py3-none-any.whl → 0.12.2__py3-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 (77) hide show
  1. java_codebase_rag-0.12.2.dist-info/METADATA +35 -0
  2. java_codebase_rag-0.12.2.dist-info/RECORD +4 -0
  3. {java_codebase_rag-0.12.0.dist-info → java_codebase_rag-0.12.2.dist-info}/WHEEL +1 -1
  4. java_codebase_rag/_deprecation.py +0 -103
  5. java_codebase_rag/_fdlimit.py +0 -56
  6. java_codebase_rag/_stdio.py +0 -32
  7. java_codebase_rag/_version.py +0 -35
  8. java_codebase_rag/absence/__init__.py +0 -0
  9. java_codebase_rag/absence/absence_diagnosis.py +0 -700
  10. java_codebase_rag/absence/absence_types.py +0 -124
  11. java_codebase_rag/absence/absence_vocab.py +0 -460
  12. java_codebase_rag/analysis/__init__.py +0 -0
  13. java_codebase_rag/analysis/pr_analysis.py +0 -563
  14. java_codebase_rag/analysis/resolve_service.py +0 -740
  15. java_codebase_rag/ast/__init__.py +0 -0
  16. java_codebase_rag/ast/ast_java.py +0 -2847
  17. java_codebase_rag/ast/ast_kotlin.py +0 -1794
  18. java_codebase_rag/ast/brownfield_events.py +0 -58
  19. java_codebase_rag/ast/chunk_heuristics.py +0 -83
  20. java_codebase_rag/ast/language.py +0 -117
  21. java_codebase_rag/cli.py +0 -1215
  22. java_codebase_rag/cli_dispatch.py +0 -251
  23. java_codebase_rag/cli_format.py +0 -85
  24. java_codebase_rag/cli_progress.py +0 -94
  25. java_codebase_rag/config.py +0 -833
  26. java_codebase_rag/eval/__init__.py +0 -1
  27. java_codebase_rag/eval/ground_truth.py +0 -100
  28. java_codebase_rag/eval/metrics.py +0 -107
  29. java_codebase_rag/eval/runner.py +0 -556
  30. java_codebase_rag/graph/__init__.py +0 -0
  31. java_codebase_rag/graph/build_ast_graph.py +0 -4593
  32. java_codebase_rag/graph/graph_enrich.py +0 -1940
  33. java_codebase_rag/graph/graph_types.py +0 -224
  34. java_codebase_rag/graph/java_ontology.py +0 -465
  35. java_codebase_rag/graph/ladybug_queries.py +0 -2213
  36. java_codebase_rag/graph/path_filtering.py +0 -509
  37. java_codebase_rag/index/__init__.py +0 -0
  38. java_codebase_rag/index/java_index_flow_lancedb.py +0 -879
  39. java_codebase_rag/index/java_index_v1_common.py +0 -33
  40. java_codebase_rag/install_data/__init__.py +0 -0
  41. java_codebase_rag/install_data/agents/explorer-rag-cli.md +0 -110
  42. java_codebase_rag/install_data/agents/explorer-rag-enhanced.md +0 -152
  43. java_codebase_rag/install_data/skills/explore-codebase/SKILL.md +0 -165
  44. java_codebase_rag/install_data/skills/explore-codebase-cli/SKILL.md +0 -107
  45. java_codebase_rag/installer.py +0 -2188
  46. java_codebase_rag/jrag.py +0 -4545
  47. java_codebase_rag/jrag_envelope.py +0 -1107
  48. java_codebase_rag/jrag_hints.py +0 -204
  49. java_codebase_rag/jrag_render.py +0 -926
  50. java_codebase_rag/lance_optimize.py +0 -264
  51. java_codebase_rag/mcp/__init__.py +0 -0
  52. java_codebase_rag/mcp/mcp_hints.py +0 -932
  53. java_codebase_rag/mcp/mcp_v2.py +0 -1916
  54. java_codebase_rag/mcp/server.py +0 -886
  55. java_codebase_rag/pipeline.py +0 -531
  56. java_codebase_rag/progress.py +0 -570
  57. java_codebase_rag/read_payloads.py +0 -781
  58. java_codebase_rag/search/__init__.py +0 -0
  59. java_codebase_rag/search/index_common.py +0 -10
  60. java_codebase_rag/search/search_lancedb.py +0 -1296
  61. java_codebase_rag/search/search_lexical.py +0 -449
  62. java_codebase_rag/search/search_scoring.py +0 -537
  63. java_codebase_rag/watch/__init__.py +0 -0
  64. java_codebase_rag/watch/client.py +0 -230
  65. java_codebase_rag/watch/daemon.py +0 -396
  66. java_codebase_rag/watch/lock.py +0 -201
  67. java_codebase_rag/watch/paths.py +0 -76
  68. java_codebase_rag/watch/protocol.py +0 -122
  69. java_codebase_rag/watch/server.py +0 -273
  70. java_codebase_rag/watch/warm.py +0 -105
  71. java_codebase_rag/watch/watcher.py +0 -394
  72. java_codebase_rag-0.12.0.dist-info/METADATA +0 -340
  73. java_codebase_rag-0.12.0.dist-info/RECORD +0 -75
  74. java_codebase_rag-0.12.0.dist-info/entry_points.txt +0 -5
  75. java_codebase_rag-0.12.0.dist-info/licenses/LICENSE +0 -21
  76. java_codebase_rag-0.12.0.dist-info/top_level.txt +0 -1
  77. /java_codebase_rag/__init__.py → /java_codebase_rag-0.12.2.dist-info/top_level.txt +0 -0
@@ -1,340 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: java-codebase-rag
3
- Version: 0.12.0
4
- Summary: jrag (formerly java-codebase-rag) — MCP server + jrag CLI for semantic + structural search over Java/Kotlin codebases
5
- Author: HumanBean17
6
- License-Expression: MIT
7
- Project-URL: Homepage, https://github.com/HumanBean17/jrag
8
- Project-URL: Repository, https://github.com/HumanBean17/jrag
9
- Project-URL: Issues, https://github.com/HumanBean17/jrag/issues
10
- Keywords: jrag,java,mcp,rag,code-search,graph,lancedb,ladybug
11
- Classifier: Development Status :: 3 - Alpha
12
- Classifier: Intended Audience :: Developers
13
- Classifier: Programming Language :: Python :: 3
14
- Classifier: Programming Language :: Python :: 3.11
15
- Classifier: Programming Language :: Python :: 3.12
16
- Classifier: Programming Language :: Python :: 3.13
17
- Classifier: Topic :: Software Development :: Libraries
18
- Classifier: Operating System :: POSIX :: Linux
19
- Classifier: Operating System :: MacOS :: MacOS X
20
- Classifier: Operating System :: Microsoft :: Windows
21
- Requires-Python: >=3.11
22
- Description-Content-Type: text/markdown
23
- License-File: LICENSE
24
- Requires-Dist: cocoindex[lancedb]<2,>=1.0.15; sys_platform != "darwin" or platform_machine != "x86_64"
25
- Requires-Dist: ladybug<0.18,>=0.17.1
26
- Requires-Dist: lancedb<0.36,>=0.34; sys_platform != "darwin" or platform_machine != "x86_64"
27
- Requires-Dist: mcp<2,>=1.27.0
28
- Requires-Dist: numpy<2.5,>=1.26.4
29
- Requires-Dist: pathspec<2,>=1.0.4
30
- Requires-Dist: pyarrow<26,>=23.0.1
31
- Requires-Dist: pydantic<3,>=2.0
32
- Requires-Dist: PyYAML<7,>=6.0.3
33
- Requires-Dist: questionary<3,>=2.0
34
- Requires-Dist: rich<16,>=14
35
- Requires-Dist: sentence-transformers<6,>=5.4.0; sys_platform != "darwin" or platform_machine != "x86_64"
36
- Requires-Dist: tree-sitter<0.26,>=0.25.2
37
- Requires-Dist: tree-sitter-java<0.24,>=0.23.5
38
- Requires-Dist: tree-sitter-kotlin<2,>=1.1.0
39
- Requires-Dist: unidiff<1,>=0.7.3
40
- Requires-Dist: watchdog<7,>=6
41
- Provides-Extra: dev
42
- Requires-Dist: pytest>=7; extra == "dev"
43
- Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
44
- Requires-Dist: pytest-xdist>=3; extra == "dev"
45
- Requires-Dist: ruff>=0.4; extra == "dev"
46
- Dynamic: license-file
47
-
48
- # jrag
49
-
50
- A graph-native code intelligence layer for Java microservice estates, surfaced through the **`jrag` CLI** — one command per engineering intent. A **legacy MCP server** (`search` / `find` / `describe` / `neighbors` / `resolve`) is also available for existing setups. Both are thin surfaces over the same **AST Graph**: a deterministic property graph extracted from Java source with tree-sitter, stored **locally** in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks). There is no server to host and no cloud round-trip — the index lives on your disk and your source never leaves the machine. Both surfaces collapse onto three primitive operations: **locate**, **inspect**, **walk**.
51
-
52
- > **What this is: a GPS for code navigation**, not a reasoning engine.
53
- > Agents use a simple loop:
54
- >
55
- > 1. **Locate** entry nodes (`jrag find`, `jrag search`, or identifier-shaped lookup)
56
- > 2. **Inspect** what a node is (`jrag inspect`)
57
- > 3. **Walk** one hop at a time (`jrag callers` / `callees` / `hierarchy` / …) until enough evidence is gathered
58
- >
59
- > The tool exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
60
-
61
- For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
62
-
63
- ---
64
-
65
- ## Why this exists
66
-
67
- Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
68
-
69
- - **Hybrid RAG + AST Graph, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (the LadybugDB AST Graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `EXPOSES`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
70
-
71
- - **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `COMPONENT`, `CONFIG`, `ENTITY`, `CLIENT`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
72
-
73
- - **Ranking specialized for Java codebases.** The composite ranker is aware of role, microservice, and FQN structure — not a generic BM25. A search for `"chat ingress"` surfaces controllers before utility classes; a search scoped to one microservice doesn't drown in matches from the other 19. Defaults are tuned on the bank-chat fixture and exposed in `docs/CONFIGURATION.md` for per-repo overrides.
74
-
75
- - **Cross-service resolution + system-level navigation.** `HTTP_CALLS` and `ASYNC_CALLS` edges connect Clients and Producers in one microservice to Routes and Handlers in another, resolved at index time from URL/topic strings + Spring `@FeignClient` / `RestTemplate` conventions. `/who-hits-route`, `/trace-request-flow`, and `/impact-of` use these to answer questions a single-service tool fundamentally can't — "who calls this REST endpoint from outside this service", "trace this Kafka message end-to-end", "if I change this DTO, which services break".
76
-
77
- - **Brownfield annotations as a first-class override.** Real Java estates have hand-rolled HTTP clients, dynamic topic names, reflection-heavy routing. `@CodebaseHttpRoute`, `@CodebaseAsyncRoute`, `@CodebaseHttpClient`, and `@CodebaseProducer` let you pin the truth in source. They have **exclusive priority** — when a symbol is annotated, framework-convention inference is skipped entirely. You get a correct graph on legacy code without rewriting it.
78
-
79
- The rest of this README is the install, the tool/command orientation, and the reference for putting that to work.
80
-
81
- ---
82
-
83
- ## Install
84
-
85
- ```bash
86
- pip install jrag-cli
87
- ```
88
-
89
- Python **3.11+** required, on **Linux, macOS, and Windows**. On Linux, Windows, and **Apple Silicon** Macs every native dependency (LanceDB, LadybugDB, CocoIndex) ships a wheel and you get the full semantic + graph search. **Intel Macs (x86_64) install graph-only**: PyTorch ≥2.3 and LanceDB ≥0.26 dropped macOS Intel wheels, so the vector stack is auto-excluded via PEP 508 markers — `pip install jrag-cli` works out of the box, the graph layer (`find` / `describe` / `neighbors` / `resolve`) is fully usable, and the `search` tool falls back to **lexical search** over the symbol graph — BM25-ranked over a LadybugDB full-text index (same tool contract, keyword-ranked instead of semantic; an advisory notes the mode). Semantic/vector search needs Apple Silicon, Linux, or Windows. After install, `jrag --help` should print the CLI groups.
90
- The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase` on platforms that have it (it is absent on Intel Mac).
91
-
92
- **Kotlin (`.kt`) is indexed alongside Java (`.java`)** — both feed one merged AST graph (a Kotlin class can implement a Java interface and vice versa). Kotlin parsing requires the `tree-sitter-kotlin` grammar; if it fails to import, `.kt` files are skipped and Java-only indexing proceeds. **Intel Mac note:** `tree-sitter-kotlin` currently ships a macOS x86_64 wheel, so Kotlin indexing works there today; if a future release drops that wheel, Kotlin indexing degrades off on Intel Mac while the Java graph keeps working. See `docs/CODEBASE_REQUIREMENTS.md` A.1 for the v1 Kotlin limitations (extension-function calls unresolved; non-Spring frameworks out of scope; generated-code classification Java-only).
93
-
94
- ### Interactive setup (recommended)
95
-
96
- Run `jrag install` from your Java project root to launch an interactive setup wizard that:
97
-
98
- 1. Detects Java source directories (Maven/Gradle modules)
99
- 2. Configures the embedding model (auto-downloads ~90MB or uses a local path)
100
- 3. Selects agent hosts (Claude Code, Qwen Code, GigaCode)
101
- 4. Deploys MCP registration, skill, and agent artifacts
102
- 5. Generates `.java-codebase-rag.yml` configuration
103
- 6. Runs `init` to build the index
104
-
105
- ```bash
106
- # Interactive mode
107
- jrag install
108
-
109
- # Non-interactive mode (for CI/automation)
110
- jrag install --non-interactive --agent claude-code
111
- ```
112
-
113
- After `pip install --upgrade jrag-cli`, run `jrag update` to refresh shipped artifacts and catch up the index (Lance + graph).
114
-
115
- All indexing lifecycle commands (`init`, `increment`, `reprocess`, `install`, `update`) show a unified `Vectors → Optimize → Graph` progress bar on stderr during the index build (powered by `rich`); pass `--quiet` to suppress it.
116
-
117
- ### Manual registration
118
-
119
- If you prefer manual configuration, see [`docs/JRAG-CLI.md`](./docs/JRAG-CLI.md) for the full CLI reference.
120
-
121
- > **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/LadybugDB schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
122
-
123
- ---
124
-
125
- ## Tools & commands at a glance
126
-
127
- `jrag` is the default and recommended surface (`jrag install --surface cli`). The **MCP server** (`--surface mcp`) is kept as a **legacy** option for existing setups. Both surfaces walk the same LanceDB vectors + LadybugDB **AST Graph**. Switch an existing install later with `jrag update --surface mcp|cli`.
128
-
129
- **CLI surface — `jrag`, one command per engineering intent**
130
-
131
- ```bash
132
- # Orientation
133
- jrag status # index health (ontology version, freshness, counts)
134
- jrag microservices # microservices with resolved type counts
135
- jrag map # counts per kind per service/module
136
- jrag map --by module # group by module instead (--module filters)
137
- jrag conventions # dominant roles + framework tallies
138
- jrag overview chat-core # bundle for a microservice
139
- jrag overview /chat/assign # route flow (inbound callers + outbound CALLS)
140
- jrag overview banking.chat # topic producers + consumers
141
- jrag overview chat-core --as microservice # override auto-detection
142
-
143
- # Locate
144
- jrag find ChatService # exact name/FQN lookup (symbols)
145
- jrag find --role CONTROLLER # filter mode (NodeFilter flags)
146
- jrag inspect ChatService # full node details + edge_summary
147
- jrag outline src/main/.../Foo.java # all symbols declared in a file
148
- jrag imports src/main/.../Foo.java # imports resolved to graph nodes
149
-
150
- # Listings
151
- jrag http-routes # HTTP routes
152
- jrag http-clients # HTTP clients (Feign / RestTemplate / WebClient)
153
- jrag producers # async message producers (Kafka / StreamBridge)
154
- jrag topics # message topics grouped by producer
155
- jrag jobs # scheduled tasks (@Scheduled)
156
- jrag listeners # message listeners (@KafkaListener etc.)
157
- jrag entities # JPA entities
158
-
159
- # Traversals (all resolve-first)
160
- jrag callers ChatService#assign(Request) # who calls me?
161
- jrag callers ChatIngressController # controller: also lists its EXPOSES routes
162
- jrag callees ChatService#assign(Request) # what do I call?
163
- jrag hierarchy AbstractBase # type tree (parents + children)
164
- jrag implementations PaymentProcessor # classes implementing an interface
165
- jrag subclasses AbstractRepository # classes extending a type
166
- jrag overrides Impl#run() # methods this overrides (dispatch UP)
167
- jrag overridden-by Iface#run() # methods overriding this (dispatch DOWN)
168
- jrag dependents PaymentGateway # who injects this type?
169
- jrag dependencies ChatService # types this injects
170
- jrag impact PaymentGateway # fleet-wide blast radius
171
- jrag decompose ChatIngressController#assign # role-waterfall flow
172
- jrag flow /chat/assign # request flow through a route
173
- jrag connection chat-core # cross-service connections
174
-
175
- # Semantic search
176
- jrag search "assign a chat agent" # semantic over Lance (java table)
177
- jrag search "kafka" --table all # java + sql + yaml tables
178
- jrag search "audit" --hybrid # vector + keyword hybrid
179
- jrag search "audit" --offset 5 # paginated
180
- ```
181
-
182
- Every `<query>` command takes human-readable identifiers (FQN / simple name / route path / topic) — never raw node IDs. Output contract, flags, and the resolve-first rule are in [`jrag` — agent CLI](#jrag--agent-cli) below.
183
-
184
- **MCP surface — five tools over stdio (legacy)**
185
-
186
- | Tool | Purpose | Required args |
187
- |---|---|---|
188
- | `search` | Locate nodes by NL / code text. | `query` |
189
- | `find` | Locate nodes by structured filter. | `kind`, `filter` |
190
- | `describe` | Full record + edge counts for one node. | `id` |
191
- | `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
192
- | `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
193
-
194
- Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
195
-
196
- ### Three-layer architecture
197
-
198
- Layer 1 (storage) → Layer 2 (the `jrag` CLI, **or** the legacy 5-tool MCP) → Layer 3 (skill). The CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI; the MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the legacy 5-tool MCP (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
199
-
200
- ---
201
-
202
- ## Configuration
203
-
204
- The operator-facing surface is small: pick an index dir, pick an embedding model, optionally drop a `.java-codebase-rag.yml` at your project root for microservice layout and brownfield overrides.
205
-
206
- | If you want to… | See |
207
- |---|---|
208
- | Set env vars and override precedence | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §1 |
209
- | Configure microservice roots and embeddings via YAML | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §2 |
210
- | Understand the graph (nodes, edges, capabilities, ranking) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §3 |
211
- | Steer a brownfield Java tree (custom stereotypes, non-Spring stacks) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §4 |
212
- | Control which files the indexer walks | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §5 |
213
- | Check whether your repo fits this tool's assumptions | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) |
214
-
215
- ---
216
-
217
- ## CLI cheat sheet
218
-
219
- Run `jrag --help` to list grouped subcommands. Operator playbook with workflows, exit codes, and env alignment lives in [`docs/JRAG-CLI.md`](./docs/JRAG-CLI.md).
220
-
221
- | Group | Subcommand | What it does |
222
- |---|---|---|
223
- | Setup | `install` | Interactive setup wizard: config, MCP registration, skill/agent deployment, indexing. |
224
- | Setup | `update` | Refresh shipped artifacts (skill, agent, MCP entry) + incremental Lance/graph catch-up after pip upgrade. |
225
- | Lifecycle | `init` | First-time index. Refuses if artifacts already exist. |
226
- | Lifecycle | `increment` | CocoIndex catch-up + incremental LadybugDB update. `--vectors-only` for Lance only. |
227
- | Lifecycle | `reprocess` | Full Lance + LadybugDB rebuild. `--vectors-only` / `--graph-only` for a single phase. |
228
- | Lifecycle | `erase` | Delete index artifacts. Requires `--yes` or TTY confirm. |
229
- | Introspection | `meta`, `tables`, `diagnose-ignore`, `unresolved-calls` | Health, table listing, ignore-layer diagnostics, receiver-failure call sites. |
230
- | Analysis | `analyze-pr` | Blast-radius / risk from a unified diff. |
231
-
232
- ---
233
-
234
- ## jrag — agent CLI
235
-
236
- `jrag` is the unified console script (operator + agent verbs) built for AI
237
- coding agents and operators alike. It gives the agent **one command per engineering intent** and
238
- takes human-readable identifiers (FQN / simple name / route path / topic) —
239
- never raw node IDs. Every `<query>` command resolves the identifier via
240
- `resolve_v2` as the first step; on `many` it returns candidates and stops, on
241
- `none` it returns `not_found`. Auto-pick is forbidden.
242
-
243
- The default output is compact text (a deliberate divergence from the operator
244
- CLI's TTY heuristic — `jrag` is agent-facing/non-TTY). `--format json` emits the
245
- shared envelope verbatim. Every command emits the same envelope shape:
246
-
247
- ```json
248
- {
249
- "status": "ok",
250
- "nodes": {"com.example.Foo": {"kind": "symbol", "fqn": "com.example.Foo"}},
251
- "edges": [{"edge_type": "CALLS", "confidence": 0.9, "target": "com.example.Bar#baz()"}],
252
- "root": "com.example.Foo",
253
- "agent_next_actions": ["jrag callees com.example.Foo#bar()"],
254
- "truncated": false
255
- }
256
- ```
257
-
258
- No raw graph node id ever appears on either surface: `nodes` is keyed by each
259
- node's natural identifier (FQN for symbols, `METHOD path` for routes,
260
- `member_fqn->target` for clients, `topic:<name>` for topics), `root` is the
261
- root's natural identifier, and each edge carries `target` (the referenced node's
262
- identifier) instead of a graph id. The agent reuses these identifiers directly
263
- as the next command's `<query>` — there is nothing else to pass.
264
-
265
- `agent_next_actions` carries up to 5 contextual next-step hints (e.g. after
266
- `inspect`, the agent sees `jrag callers <fqn>`, `jrag callees <fqn>`, etc. for
267
- the edges the root actually has). Omitted from JSON when empty.
268
-
269
- The full command catalog lives in [Tools & commands at a glance](#tools--commands-at-a-glance).
270
-
271
- ### Flags
272
-
273
- | Flag | Scope | Effect |
274
- |------|-------|--------|
275
- | `--format text\|json` | all | output format (default: text) |
276
- | `--service <name>` | listings/traversals | filter by microservice |
277
- | `--module <name>` | listings/traversals | filter by module |
278
- | `--limit <n>` | listings/traversals | cap results (default 20; `limit+1` fetch detects truncation) |
279
- | `--offset <n>` | `find`, `search` only | paginate (other commands reject it) |
280
- | `--kind symbol\|route\|client\|producer` | `<query>` commands | resolve hint |
281
- | `--java-kind`, `--role`, `--fqn-contains` | `<query>` commands | client-side post-filters |
282
- | `--index-dir <path>` | all | override index directory |
283
-
284
- `--offset` is intentionally NOT a global flag: only `find` and `search` route
285
- through backends that accept it. Every other command rejects it.
286
-
287
- A missing or stale index produces an actionable `status: error` envelope (exit
288
- 2) rather than a traceback:
289
-
290
- ```
291
- error: No index at /path/to/code_graph.lbug. Run: jrag init --source-root <root>
292
- ```
293
-
294
- See [`plans/active/PLAN-JRAG-CLI.md`](./plans/active/PLAN-JRAG-CLI.md) for the
295
- full design and per-PR breakdown.
296
-
297
- ---
298
-
299
- ## Further reading
300
-
301
- | Document | What's in it |
302
- |---|---|
303
- | [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) | Architecture report — design rationale, GPS metaphor, three-layer architecture, design principles, future work. |
304
- | [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md) | Agent-facing guide. Copy-paste into `QWEN.md` / `CLAUDE.md` / `AGENTS.md`. |
305
- | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
306
- | [`docs/JRAG-CLI.md`](./docs/JRAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
307
- | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
308
- | [`skills/`](./skills/) | `/explore-codebase-cli` (CLI surface) + `/explore-codebase` (legacy MCP surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
309
- | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
310
- | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
311
- | [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |
312
-
313
- ---
314
-
315
- ## Install from source (contributors)
316
-
317
- ```bash
318
- git clone https://github.com/HumanBean17/jrag
319
- cd jrag
320
- python3 -m venv .venv
321
- .venv/bin/pip install -e ".[dev]"
322
- ```
323
-
324
- The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.
325
-
326
- The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `SBERT_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
327
-
328
- ---
329
-
330
- ## Roadmap (graph layer)
331
-
332
- - `get_service_topology` — microservice-level summary aggregating `HTTP_CALLS` / `ASYNC_CALLS`.
333
- - Agentic routing layer (query classifier → vector / graph / both).
334
- - Optional `codegraph_nodes` LanceDB table embedding symbol summaries so the graph itself is vector-searchable.
335
-
336
- ---
337
-
338
- ## Built on
339
-
340
- The indexing pipeline runs on [**CocoIndex**](https://github.com/cocoindex-io/cocoindex) — an open-source data indexing framework that powers the vector store lifecycle (`init`, `increment`, `reprocess`, `erase`) behind every `jrag` index.
@@ -1,75 +0,0 @@
1
- java_codebase_rag/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
2
- java_codebase_rag/_deprecation.py,sha256=qOxHM4AYUUBQPIgTMXODPmnxjrpMoYweMzjOoqBkQKc,4196
3
- java_codebase_rag/_fdlimit.py,sha256=vkwjsPbZfxzZ2DZTPWO5DxtuNlLzOADzIq07iYX7GCU,2465
4
- java_codebase_rag/_stdio.py,sha256=TDNbpt2EP0_Zd622ihdlKwlMfxkKHWOfgLVcU6TcNbo,1458
5
- java_codebase_rag/_version.py,sha256=-6MchHEyRglldb52uN12r226NUEVAmks9PTK8U1t_Yc,1347
6
- java_codebase_rag/cli.py,sha256=nLBnGbbZhNNB6aO85LpnKdLJ9pBrWjaPhQcY1-kEb_I,47500
7
- java_codebase_rag/cli_dispatch.py,sha256=hYBVV5KAiftcdF9Kh3E_tIYBaeFfWAnr0ATQvxH01Ok,9690
8
- java_codebase_rag/cli_format.py,sha256=CT7-xdwZ0bMCdP68_UOwkvm-mnLluU3LutlM-mDNk60,1839
9
- java_codebase_rag/cli_progress.py,sha256=q6Wh97yzLGs1B8UFk_WAKivfQu7Y5RnUUE-T2YHWkIs,3237
10
- java_codebase_rag/config.py,sha256=Snlj6z8pJD6OYZL8pz6bATunulyhJLpVymUORY2QUjA,33179
11
- java_codebase_rag/installer.py,sha256=efxkNxbcoxKFzqTe9-IeVlRlMxlcsYZY9Kve_HPxJO4,79734
12
- java_codebase_rag/jrag.py,sha256=t_QXmh-jmw1P7T7XaIydARNnxd12mpL6_5xSv0uWaSI,198220
13
- java_codebase_rag/jrag_envelope.py,sha256=I5q7E3DmuJBnDl1iv7bW2NucPJ2YxlmNEtM2dau18Vw,48730
14
- java_codebase_rag/jrag_hints.py,sha256=aazBRI3pOeyq2IjQuoMzDkA-1cB_tTGbVcguX3BzOiQ,9286
15
- java_codebase_rag/jrag_render.py,sha256=xYK-0YmUMwEb4w4o6rjkrn-maHhY2oEqKgLqKQqaliE,42829
16
- java_codebase_rag/lance_optimize.py,sha256=0yaCEgLc6MiBJpG2N1cNXQIEtKvBz2fSHQjDDRf9B-4,11879
17
- java_codebase_rag/pipeline.py,sha256=fwTAuIsMBGUGBWnp2xi9brlY8zTzJ1Szh6bztQ4jKg8,21367
18
- java_codebase_rag/progress.py,sha256=73uuL-wZYcdkkKCgRwdzVturT5FH1Ek2-PdxYHKg7ZI,23199
19
- java_codebase_rag/read_payloads.py,sha256=CCNdFYp_JDRQGnQh3mm9POUq4jG_FL2YsVARITsgsaU,31711
20
- java_codebase_rag/absence/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
21
- java_codebase_rag/absence/absence_diagnosis.py,sha256=RJNlycQY28fL5h1e7Kupaff-xabLzfzbbXLM-VSReBc,27631
22
- java_codebase_rag/absence/absence_types.py,sha256=BHOwTVrUAiALFuh4CxX-1hHvxmoG2zYSAcMmJocGZAc,4244
23
- java_codebase_rag/absence/absence_vocab.py,sha256=t2OYhel70j6ZSlP01xh6kvlvTdygaF6IBEhuTThCiaw,16366
24
- java_codebase_rag/analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
25
- java_codebase_rag/analysis/pr_analysis.py,sha256=A-nE5sftlcg02esQ-ZQxZvvepEUy07zbVUG-b-bgJlo,19711
26
- java_codebase_rag/analysis/resolve_service.py,sha256=vVnCRXDQlFhQfIZljh4Jk5lL63IXC7lEArRWk0Hcs34,28715
27
- java_codebase_rag/ast/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
28
- java_codebase_rag/ast/ast_java.py,sha256=UZtCtbt9DcC9QpDu4kThxWgALKyveyiBrbmxZCbWjlE,100738
29
- java_codebase_rag/ast/ast_kotlin.py,sha256=qDyqvdE5ORO9nJ2gXe_13ZJFI88IHpkoe52OK6R3vdA,70564
30
- java_codebase_rag/ast/brownfield_events.py,sha256=yxXkKDgMb3VPtaiakGzncHM_EGnda8xIue6w90yYp8s,2055
31
- java_codebase_rag/ast/chunk_heuristics.py,sha256=sn0SvGPkXChM_Dxn7bIRZOWPfCAUviPntRa8t-U894s,2992
32
- java_codebase_rag/ast/language.py,sha256=6WssjRjYsqXX_64QVca65g_qMqVr5OPjUtHDjKmMy1Y,4259
33
- java_codebase_rag/eval/__init__.py,sha256=V49SsVzkfHmVhRGMl9KbzMlxDSI8aHZA1YmxzgzNtYo,30
34
- java_codebase_rag/eval/ground_truth.py,sha256=q0gzsCF6hqR-NcMRNDDMUlvOA13RCcGcVLWWqlA4syY,3246
35
- java_codebase_rag/eval/metrics.py,sha256=nEDbN3VjYLUwyAvNcd8w4Kmjm0PlgX_Mt6cfOmH7f9k,3118
36
- java_codebase_rag/eval/runner.py,sha256=6RzoWcYcf2ZHmytzq8wXEUqogkx580kqFW7BNmWSjWk,20154
37
- java_codebase_rag/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
38
- java_codebase_rag/graph/build_ast_graph.py,sha256=U1JRR9PMmM9-oLttmYBsDrNVuA6KY58tDsl_TZhu0Bc,189081
39
- java_codebase_rag/graph/graph_enrich.py,sha256=GxptfAhc3Gd7liXtrn7m3rYQNMD57HFflRMPRrvDsQE,72725
40
- java_codebase_rag/graph/graph_types.py,sha256=VKTnJZL1_J4bsLGdXIKCsD0FkW6uvqoG8oJfvChm_SI,9057
41
- java_codebase_rag/graph/java_ontology.py,sha256=Fa6iCsrBLPc2lCl-6VR2qHN4Q9Ix8Gps3thQhIEGjrM,17241
42
- java_codebase_rag/graph/ladybug_queries.py,sha256=qdneNIYtJvNkMBfWub4hsB7iemXnfdiVbaZoWakplgk,103050
43
- java_codebase_rag/graph/path_filtering.py,sha256=odOH1lZXh3_uumcc8gvpE96ffUpGkRmUFDUL_vwaFVc,19099
44
- java_codebase_rag/index/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
45
- java_codebase_rag/index/java_index_flow_lancedb.py,sha256=NnZkVhka_Ubbndv-rhvosyXZHxD028yDxsa7xTYFb_M,36159
46
- java_codebase_rag/index/java_index_v1_common.py,sha256=nF1KrSqboF_RRvWerG9knRRFmWwsrG_CvhgnsoZ8KqA,1154
47
- java_codebase_rag/install_data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
48
- java_codebase_rag/install_data/agents/explorer-rag-cli.md,sha256=wWhK4gJkxBlW6gTB1mSdUpMqfGHrnNoEqNakPBkZLEg,11683
49
- java_codebase_rag/install_data/agents/explorer-rag-enhanced.md,sha256=q3tOSGHpnqYr06w48V9rMZxPAqGEDnvgio2Ih8JC0fY,10354
50
- java_codebase_rag/install_data/skills/explore-codebase/SKILL.md,sha256=uDz1eIDENx9nF-8qzHjktqVS7G8G9BiN2pX7cYTsfmg,11477
51
- java_codebase_rag/install_data/skills/explore-codebase-cli/SKILL.md,sha256=b-Ot3e0J4wv-RyJ6eevjrj7arY_R-Wzb-DSghneQxMU,11244
52
- java_codebase_rag/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
53
- java_codebase_rag/mcp/mcp_hints.py,sha256=eJzm_HpfaEKblT4-FW_9bgvDemZYs3E6exGeznflrXM,42536
54
- java_codebase_rag/mcp/mcp_v2.py,sha256=70POeJ_O5U_Jjf0SGH9lyK1f5XCIRl25KRSrDxkUZuk,80422
55
- java_codebase_rag/mcp/server.py,sha256=w7q6z_yIbaFYd83KjSkY5XIR6-jL0_7Q-qWjMF31D-Y,40980
56
- java_codebase_rag/search/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
57
- java_codebase_rag/search/index_common.py,sha256=HT6FKHFJ084eFvd3fR1j8z8gf4eWoPHVW8GXLpw464I,285
58
- java_codebase_rag/search/search_lancedb.py,sha256=MxfTivzeMbScmYIf9s8nKSGCmNr5gMGDXldZotAfW-8,49368
59
- java_codebase_rag/search/search_lexical.py,sha256=wVG4tZ2pc7zX4vWewqj9ONMoZ0cZRJkcMZa3fEKUw6o,19935
60
- java_codebase_rag/search/search_scoring.py,sha256=SaLYiZP_udyAYUSfLhehX4J1Do8uA8kSlFoiLWYle6s,21374
61
- java_codebase_rag/watch/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
62
- java_codebase_rag/watch/client.py,sha256=PO1uyllGZWoYgYYgm6vToCvaILkp0coXfXCEitzWXMU,9258
63
- java_codebase_rag/watch/daemon.py,sha256=JusMIL_cWxnJXaC0Ix4pOhl-GKMH7Cj5ZBH9CSJtGyo,17633
64
- java_codebase_rag/watch/lock.py,sha256=-TlYIeXSOqxFKvPxFT9LH1aka5-YRNd5BHnJ1s9V9-M,7551
65
- java_codebase_rag/watch/paths.py,sha256=UXmw19O2ILr0_yWgeyd-j6Qn2y0MO4ejspfLBcLol0w,2368
66
- java_codebase_rag/watch/protocol.py,sha256=Vj16d0d0eA7XiLFX6o7JMY-I-mGva9VRxC41ZSbDVy4,3061
67
- java_codebase_rag/watch/server.py,sha256=GUyCDmbl30wm9GhWTBh-K_BEhFSCHiM2kahmncMGf5E,11168
68
- java_codebase_rag/watch/warm.py,sha256=EN_39jVV1Kohsq8OI2LqGdTz_X-OCy4s4GWykiDAK7k,5113
69
- java_codebase_rag/watch/watcher.py,sha256=M9MKBI2P8w3Os2I9JM_0oElk5eeJ-DCC5vB3aAoRrdQ,17827
70
- java_codebase_rag-0.12.0.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
71
- java_codebase_rag-0.12.0.dist-info/METADATA,sha256=Q4UEAjZ79KdVbd21YblRK0vmkgWmEZwREJ-OfE8P_YM,21365
72
- java_codebase_rag-0.12.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
73
- java_codebase_rag-0.12.0.dist-info/entry_points.txt,sha256=S7ng8YydbGe97wugiCOgfI8xu04aKuLzSioSNH1rmcQ,252
74
- java_codebase_rag-0.12.0.dist-info/top_level.txt,sha256=u2i_IKLLOkYyNE32m4TIED0vtKtQDdPEVqRtNuhC1Hk,18
75
- java_codebase_rag-0.12.0.dist-info/RECORD,,
@@ -1,5 +0,0 @@
1
- [console_scripts]
2
- java-codebase-rag = java_codebase_rag.cli_dispatch:_console_script_main
3
- java-codebase-rag-mcp = java_codebase_rag.mcp.server:main
4
- jrag = java_codebase_rag.cli_dispatch:_console_script_main
5
- jrag-mcp = java_codebase_rag.mcp.server:main
@@ -1,21 +0,0 @@
1
- MIT License
2
-
3
- Copyright (c) 2025 HumanBean17
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
@@ -1 +0,0 @@
1
- java_codebase_rag