java-codebase-rag 0.9.7__py3-none-any.whl → 0.10.1__py3-none-any.whl

java_codebase_rag/jrag_render.py

@@ -10,12 +10,13 @@ invariant.
 """
 from __future__ import annotations
 
+import json
 from typing import Any
 
 from java_codebase_rag.absence.absence_types import AbsenceDiagnosis
 from java_codebase_rag.jrag_envelope import Envelope, project_envelope, simple_name
 
-__all__ = ["render", "tiered_name", "display_name"]
+__all__ = ["render", "tiered_name", "display_name", "count_results", "has_results"]
 
 
 # Edge labels that carry a ``confidence`` column (CALLS-family). ``conf:`` is
@@ -125,6 +126,23 @@ def _next_action_lines(envelope: Envelope) -> list[str]:
     return [f"next: {hint}" for hint in envelope.agent_next_actions[:2]]
 
 
+def _is_dynamic_topic_ref(topic: str) -> bool:
+    """True when a producer ``topic`` string is a bare Java identifier — a
+    variable or method-call name the indexer captured because it could not
+    resolve the destination at index time — rather than a real topic name.
+
+    Real topics are dotted (``banking.chat.audit``) or CONSTANT references
+    (``ChatTopics.ESCALATION``, ``OPERATOR_NOTIFICATIONS``); both contain a
+    ``.`` or ``_``. A single lowercase/identifier token (``topic``,
+    ``distributionTopic``) is a runtime reference. Used by :func:`display_name`
+    only when the producer is also ``resolved=False`` — a resolved bare token is
+    treated as a (rare) real single-word topic.
+    """
+    if "." in topic or "_" in topic:
+        return False
+    return bool(topic) and topic[0].islower() and topic.isalnum()
+
+
 def display_name(node: dict[str, Any]) -> str:
     """Best short label for a node across all kinds (symbol + route/client/producer).
 
@@ -175,6 +193,15 @@ def display_name(node: dict[str, Any]) -> str:
         base = member_fqn.rsplit(".", 1)[-1]
         topic = str(node.get("topic") or "").strip()
         if topic:
+            # An unresolved topic that is a bare Java identifier is a runtime
+            # reference the indexer could not resolve (e.g. the variable
+            # ``topic``, or ``getKafka().getDistributionTopic()`` reduced to
+            # ``distributionTopic``). Printing it verbatim would show
+            # ``→ topic`` and mislead the agent into treating the variable name
+            # as the Kafka destination; surface it as dynamic instead. Real
+            # topic names (dotted / CONSTANT) stay verbatim.
+            if node.get("resolved") is False and _is_dynamic_topic_ref(topic):
+                return f"{base} → (dynamic topic)"
             return f"{base} → {topic}"
         target = str(node.get("target_service") or "").strip()
         if target:
@@ -619,8 +646,24 @@ def _render_inspect_block(node: dict[str, Any], indent: int) -> list[str]:
             out.extend(_render_inspect_block(val, indent + 1))
         elif _is_dict_list(val):
             out.append(f"{pad}{key}:")
+            item_pad = "  " * (indent + 1)
+            # Rich items (>2 keys: e.g. ``topics`` producers) render one kv per
+            # line for readability — a wall of comma-joined keys is unreadable
+            # and hides the composed ``file`` location. Short sample items
+            # (``route_sample`` / ``client_sample``) stay on a single line.
+            rich = any(len(it) > 2 for it in val)
             for item in val:
-                out.append(f"{pad}  - {_inspect_inline(item)}")
+                if rich:
+                    # Render at indent+2 so continuation kvs align under the
+                    # first kv (which sits after the `- ` marker at indent+1).
+                    item_lines = _render_inspect_block(item, indent + 2)
+                    if not item_lines:
+                        out.append(f"{item_pad}- {{}}")
+                    else:
+                        out.append(f"{item_pad}- {item_lines[0].lstrip()}")
+                        out.extend(item_lines[1:])
+                else:
+                    out.append(f"{item_pad}- {_inspect_inline(item)}")
         else:
             out.append(f"{pad}{key}: {_inspect_inline(val)}")
     return out
@@ -717,6 +760,92 @@ def _render_text_shape(envelope: Envelope, *, noun: str, shape: str | None, deta
     return _render_scalar(envelope)
 
 
+def count_results(envelope: Envelope, shape: str | None) -> int:
+    """How many result items ``envelope`` represents, per its render shape.
+
+    The single source of truth shared by ``--count`` (output) and ``--exists``
+    (output + exit code). Counts the collection the agent thinks of as the
+    result, not the raw node dict (a traversal envelope includes the root
+    subject in ``nodes`` — counting nodes would report N+1, not N):
+
+      * ``shape="inspect"`` -> 1 when a subject resolved (else 0). ``inspect``
+        /``status``/``map``/``conventions``/``overview`` declare this shape.
+      * ``root is not None`` (traversal) -> ``len(edges)``: the callers/callees/
+        hierarchy members are the result; the root is the resolved subject.
+      * otherwise (listing) -> ``len(nodes)``.
+
+    Callers that only care about emptiness should use :func:`has_results`, which
+    also gates on ``status == "ok"`` (a ``not_found`` / ``error`` envelope has no
+    result regardless of any carried nodes/edges).
+    """
+    if shape == "inspect":
+        return 1 if envelope.nodes else 0
+    if envelope.root is not None:
+        return len(envelope.edges)
+    return len(envelope.nodes)
+
+
+def has_results(envelope: Envelope, shape: str | None) -> bool:
+    """True only when the envelope is a non-empty ``ok`` result.
+
+    ``not_found`` / ``ambiguous`` / ``error`` carry no result even when they
+    carry nodes/candidates (e.g. ambiguous candidates are narrowing hints, not
+    hits). Used by ``--exists`` for both its output and its exit code.
+    """
+    return envelope.status == "ok" and count_results(envelope, shape) > 0
+
+
+def _field_set(fields: str) -> set[str]:
+    """Parse a comma-separated ``--fields`` allowlist into a set of trimmed names."""
+    return {name.strip() for name in fields.split(",") if name.strip()}
+
+
+def _project_to_fields(envelope: Envelope, fields: str) -> Envelope:
+    """Return a copy of ``envelope`` (at FULL detail) whose nodes keep only the
+    requested field names.
+
+    ``--fields`` is an explicit allowlist that OVERRIDES ``--detail``: project to
+    full (so a ``full``-tier field like ``signature`` is available even at the
+    default detail), then keep only the requested keys per node. Names absent on
+    a node are simply not present. Graph-id fields stay stripped
+    (``project_envelope(full)`` already strips them). Edges/candidates are left
+    at full; ``--fields`` is documented as a node projection.
+
+    Delegates the envelope copy to :func:`project_envelope` (the single
+    projection seam) and only rewrites ``nodes`` on the already-copied result,
+    so the per-field Envelope construction can't drift out of sync as fields are
+    added. ``project_envelope`` returns an independent copy and the node dicts
+    are rebuilt by the comprehension, so the caller's ``envelope`` is untouched.
+    """
+    wanted = _field_set(fields)
+    projected = project_envelope(envelope, "full")
+    projected.nodes = {
+        nid: {k: v for k, v in node.items() if k in wanted}
+        for nid, node in projected.nodes.items()
+    }
+    return projected
+
+
+def _render_count(envelope: Envelope, *, fmt: str, shape: str | None) -> str:
+    """``--count`` output: bare integer (text) or ``{"status","count"}`` (json).
+
+    Non-``ok`` envelopes count as 0 (a miss / error has no result items). Text is
+    the bare count — "only the result count", script-friendly for ``$(...)``.
+    """
+    n = count_results(envelope, shape) if envelope.status == "ok" else 0
+    if fmt == "json":
+        return json.dumps({"status": envelope.status, "count": n})
+    return str(n)
+
+
+def _render_exists(envelope: Envelope, *, fmt: str, shape: str | None) -> str:
+    """``--exists`` output: ``true``/``false`` (text) or ``{"status","exists"}`` (json)."""
+    exists = has_results(envelope, shape)
+    if fmt == "json":
+        return json.dumps({"status": envelope.status, "exists": exists})
+    return "true" if exists else "false"
+
+
 def render(
     envelope: Envelope,
     *,
@@ -725,6 +854,9 @@ def render(
     noun: str = "",
     next_offset: int | None = None,
     shape: str | None = None,
+    count: bool = False,
+    exists: bool = False,
+    fields: str | None = None,
 ) -> str:
     """Dispatch on ``fmt`` (text default; json emits the projected envelope).
 
@@ -750,8 +882,33 @@ def render(
     ``nodes``/``noun`` -> listing, else scalar. Listing nodes frequently carry
     dict-valued fields after ``.model_dump()``, so inspect is NEVER inferred
     from node contents - only an explicit ``shape="inspect"`` routes there.
+
+    Output-shaping flags (issue #376), orthogonal to the command that produced
+    the envelope and honored on both text and json:
+
+      * ``exists=True`` -> ``true``/``false`` (or ``{"status","exists"}``). Takes
+        precedence over ``count`` (a gate is more specific than a tally).
+      * ``count=True`` -> the bare result count (or ``{"status","count"}``); see
+        :func:`count_results` for what is counted per shape.
+      * ``fields`` -> comma-separated node-field allowlist that OVERRIDES
+        ``--detail`` (project to full, then keep only the named fields). Applies
+        only to ``status="ok"`` output; composes with the normal render, not with
+        ``count``/``exists``. A whitespace/comma-only allowlist is treated as
+        not given (falls back to the normal projection). Primarily a JSON lever
+        (text rendering still labels rows from whatever identity fields survive
+        the allowlist).
+
+    The exit-code side of ``--exists`` is decided by the caller (``jrag._emit``)
+    via :func:`has_results` — render() only shapes output.
     """
-    projected = project_envelope(envelope, detail)
+    if exists:
+        return _render_exists(envelope, fmt=fmt, shape=shape)
+    if count:
+        return _render_count(envelope, fmt=fmt, shape=shape)
+    if fields and envelope.status == "ok" and _field_set(fields):
+        projected = _project_to_fields(envelope, fields)
+    else:
+        projected = project_envelope(envelope, detail)
     if fmt == "json":
         return projected.to_json()
     body = _render_text_shape(projected, noun=noun, shape=shape, detail=detail)

java_codebase_rag/lance_optimize.py

@@ -1,21 +1,20 @@
 """Serialized post-flow LanceDB optimize with commit-conflict retry.
 
-cocoindex 1.0.7 schedules ``table.optimize()`` (a LanceDB **Rewrite**/compaction
-transaction) as a *background* ``asyncio`` task that races concurrent
-``table.delete()`` (**Delete**) transactions emitted by later mutation batches.
-LanceDB does not allow a Rewrite to commit concurrently with a Delete
-(upstream lancedb#1504 — "We do not support concurrent deletes right now"),
-which surfaces as a flood of::
+Historically (cocoindex 1.0.7) this existed because cocoindex scheduled
+``table.optimize()`` (a LanceDB **Rewrite**/compaction) as a *background*
+``asyncio`` task that raced concurrent ``table.delete()`` (**Delete**)
+transactions — LanceDB does not allow a Rewrite to commit concurrently with a
+Delete (upstream lancedb#1504), surfacing as a flood of::
 
     RuntimeError: lance error: Retryable commit conflict for version N: \
 This Rewrite transaction was preempted by concurrent transaction Delete ...
 
-To eliminate the race, the flow (``java_index_flow_lancedb.py``) disables the
-in-flight background optimize entirely by raising
-``num_transactions_before_optimize`` to a value that is effectively never
-reached. This module then performs a *single*, serialized optimize after the
-flow returns (exit 0 → no concurrent writers), retrying the rare residual
-commit conflict that two internal compaction passes can still produce.
+cocoindex >=1.0.15 made optimize **inline and stats-driven** (only compacts
+when small fragments accumulate, inside the merge_insert commit path), so the
+race is gone and the flow no longer disables anything. This module still runs a
+*single*, serialized optimize after the flow returns (exit 0 → no concurrent
+writers) as a clean final compaction + scalar/FTS index build, retrying the rare
+residual commit conflict that two internal compaction passes can still produce.
 """
 from __future__ import annotations
 

java_codebase_rag/mcp/mcp_v2.py

@@ -1136,7 +1136,8 @@ def find_v2(
             )
             params["lim"] = fetch_cap
             rows = g._rows(  # noqa: SLF001
-                f"MATCH (s:Symbol) {where} RETURN s.id AS id, s.fqn AS fqn, s.microservice AS microservice, "
+                f"MATCH (s:Symbol) {where} RETURN s.id AS id, s.fqn AS fqn, s.name AS name, "
+                "s.filename AS filename, s.start_line AS start_line, s.microservice AS microservice, "
                 "s.module AS module, s.role AS role, s.kind AS symbol_kind, s.generated AS generated, s.generated_by AS generated_by ORDER BY s.fqn LIMIT $lim",
                 params,
             )

java_codebase_rag/pipeline.py

@@ -133,14 +133,60 @@ def _popen_capturing_stderr(
     t_err = threading.Thread(target=drain_err, name="stream-stderr", daemon=True)
     t_out.start()
     t_err.start()
+    # Wait on the CHILD before joining the drain threads. ``Popen.wait()`` is
+    # interruptible by Ctrl+C — the underlying ``os.waitpid`` returns EINTR and
+    # CPython raises ``KeyboardInterrupt`` — whereas ``Thread.join()`` blocks on
+    # an internal lock whose infinite-timeout acquire CPython never polls for
+    # signals. Joining *first* therefore made the whole indexing step ignore
+    # Ctrl+C until the child happened to close its pipes; cocoindex's teardown
+    # (and any flow-server grandchild it spawned) can hold them open for a long
+    # time, so an install/reprocess could not be aborted. The daemon drain
+    # threads keep the child's stdout/stderr pipes empty while we wait, so the
+    # child never blocks on a full pipe.
+    try:
+        code = proc.wait()
+    except BaseException:
+        # Ctrl+C or any other abort: best-effort, NON-BLOCKING child teardown
+        # so a process we spawned does not outlive us, then re-raise WITHOUT
+        # joining the drain threads. They may be blocked on a pipe the child
+        # still owns, and a join here would re-introduce the very hang this
+        # reordering fixes. The threads are daemons, so they vanish at exit.
+        _abort_child(proc)
+        raise
+    # Normal exit: the child is gone, its pipes hit EOF, and the drain threads
+    # return promptly — safe to join here. (If a pipe-inheriting grandchild
+    # lingered past the child's exit, these joins would block until it too
+    # closed its write ends — on Ctrl+C the shared-process-group SIGINT reaches
+    # it and closes them. This window is the short teardown-after-indexing phase,
+    # not the long indexing phase the wait-first reorder already made
+    # interruptible.)
     t_out.join()
     t_err.join()
     if filt is not None:
         filt.flush()
-    code = proc.wait()
     return out_buf.decode(errors="replace"), err_buf.decode(errors="replace"), code
 
 
+def _abort_child(proc: subprocess.Popen[bytes]) -> None:
+    """Best-effort, NON-BLOCKING teardown of a spawned child on an abort path.
+
+    Runs when ``proc.wait()`` raised (Ctrl+C, or any other exception). Sends
+    SIGTERM and returns immediately — this path exists to let the operator exit
+    *promptly*, and waiting for the child would defeat that. On Ctrl+C the child
+    already received SIGINT (same process group); this just guarantees teardown
+    for non-signal aborts, after which the child finishes shutting down on its
+    own. ``OSError`` (incl. ``ProcessLookupError`` — already-dead / zombie /
+    reaped) is swallowed — the only caller re-raises regardless.
+    """
+    fn = getattr(proc, "terminate", None)
+    if fn is None:
+        return
+    try:
+        fn()
+    except OSError:
+        pass
+
+
 def run_cocoindex_update(
     env: dict[str, str],
     *,