fix cli progress review issues: honest footer, gated heavy tests, quiet help

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

build_ast_graph.py

@@ -422,7 +422,7 @@ def pass1_parse(root: Path, tables: GraphTables, *, verbose: bool) -> dict[str,
         except ValueError:
             slow_sec = 0.0
     with _VerbosePassHeartbeats("[pass1]", verbose=verbose):
-        if slow_sec > 0:
+        if verbose and slow_sec > 0:
             time.sleep(slow_sec)
         for p in iter_java_source_files(root, ignore=ignore):
             n_files += 1
@@ -1415,15 +1415,15 @@ def pass4_routes(
     if verbose:
         _verbose_stderr_line(_PASS4_START)
     with _VerbosePassHeartbeats("[pass4]", verbose=verbose):
-        
+
         for ast in asts.values():
             stats.routes_skipped_unresolved += ast.routes_skipped_unresolved
-        
+
         routes_by_id: dict[str, RouteRow] = {}
         exposes_seen: set[tuple[str, str]] = set()
-        
+
         http_kinds = frozenset({"http_endpoint", "http_consumer"})
-        
+
         for member in sorted(tables.members, key=lambda m: m.node_id):
             if member.decl.is_constructor:
                 continue
@@ -1504,13 +1504,13 @@ def pass4_routes(
                             strategy=decl.resolution_strategy,
                         ),
                     )
-        
+
         tables.routes_rows = sorted(routes_by_id.values(), key=lambda r: r.id)
-        
+
         for row in tables.routes_rows:
             stats.by_framework[row.framework] += 1
             stats.by_kind[row.kind] += 1
-        
+
         n_routes = len(tables.routes_rows)
         if n_routes:
             stats.routes_resolved_pct = 100.0 * sum(
@@ -1522,7 +1522,7 @@ def pass4_routes(
         else:
             stats.routes_resolved_pct = 100.0
             stats.routes_from_brownfield_pct = 0.0
-        
+
         by_layer: dict[str, int] = defaultdict(int)
         for row in tables.routes_rows:
             by_layer[row.source_layer] += 1
@@ -1752,7 +1752,7 @@ def _phantom_async_route_id(call: OutgoingCallDecl) -> str:
                     tables.call_edge_stats.async_calls_total += 1
                     tables.call_edge_stats.async_calls_by_client_kind[call.client_kind] += 1
                     tables.call_edge_stats.async_calls_by_strategy[strategy] += 1
-    
+
         tables.routes_rows = sorted(route_rows, key=lambda r: r.id)
         tables.client_rows = sorted(tables.client_rows, key=lambda c: c.id)
         tables.declares_client_rows = sorted(
@@ -2024,7 +2024,7 @@ def _micro_factor(member: MemberEntry | None) -> float:
             tables.call_edge_stats.http_calls_match_breakdown[row.match] += 1
             if row.match == "cross_service":
                 tables.call_edge_stats.cross_service_calls_total += 1
-    
+
         for row in tables.async_call_rows:
             if row.match != "unresolved":
                 continue
@@ -2070,7 +2070,7 @@ def _micro_factor(member: MemberEntry | None) -> float:
             tables.call_edge_stats.async_calls_match_breakdown[row.match] += 1
             if row.match == "cross_service":
                 tables.call_edge_stats.cross_service_calls_total += 1
-    
+
         inbound_route_ids = {r.route_id for r in tables.http_call_rows} | {r.route_id for r in tables.async_call_rows}
         tables.routes_rows = sorted(
             [

java_codebase_rag/cli.py

@@ -132,6 +132,19 @@ def _run_with_pipeline_progress(
     try:
         code = int(work())
         return code
+    except BaseException as exc:
+        # Keep footer aligned with process outcome (main maps unhandled Exception -> exit 2).
+        if isinstance(exc, SystemExit):
+            c = exc.code
+            if isinstance(c, int):
+                code = c
+            elif c in (None, False):
+                code = 0
+            else:
+                code = 1
+        elif code == 0:
+            code = 2
+        raise
     finally:
         _pipeline_footer(subcommand, t0, code)
 
@@ -560,7 +573,11 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_index_embedding_flags(init)
-    init.add_argument("--quiet", action="store_true")
+    init.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress stderr progress relay; stdout payload unchanged.",
+    )
     init.set_defaults(handler=_cmd_init)
 
     increment = subparsers.add_parser(
@@ -569,7 +586,11 @@ def build_parser() -> argparse.ArgumentParser:
         description="Runs cocoindex catch-up (no full reprocess). Does not rebuild Kuzu; see stderr warning.",
     )
     _add_index_embedding_flags(increment)
-    increment.add_argument("--quiet", action="store_true")
+    increment.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress stderr progress relay; stdout payload unchanged.",
+    )
     increment.set_defaults(handler=_cmd_increment)
 
     reprocess = subparsers.add_parser(
@@ -581,7 +602,11 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_index_embedding_flags(reprocess)
-    reprocess.add_argument("--quiet", action="store_true")
+    reprocess.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress stderr progress relay; stdout payload unchanged.",
+    )
     _rex = reprocess.add_mutually_exclusive_group()
     _rex.add_argument(
         "--vectors-only",
@@ -602,7 +627,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     _add_index_embedding_flags(erase)
     erase.add_argument("--yes", action="store_true", help="Confirm destructive deletion (required in CI)")
-    erase.add_argument("--quiet", action="store_true")
+    erase.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress stderr progress relay; stdout payload unchanged.",
+    )
     erase.set_defaults(handler=_cmd_erase)
 
     meta = subparsers.add_parser("meta", help="Print graph meta and embedding resolution.")

tests/README.md

@@ -62,7 +62,11 @@ The session-scoped fixtures in `conftest.py` materialize Kuzu (and, where needed
 The heavier end-to-end test that runs `cocoindex` + a real LanceDB index is
 gated behind `JAVA_CODEBASE_RAG_RUN_HEAVY=1` because it downloads the embedding
 model on first run and indexes the corpus from scratch (~minute on a
-warm cache, several minutes cold).
+warm cache, several minutes cold). The same gate applies to full
+`java-codebase-rag` lifecycle subprocess checks in
+`tests/test_cli_progress_stdout_invariant.py` and the cocoindex portion of
+`tests/test_cli_quiet_parity.py` so default `pytest tests` stays fast when
+`cocoindex` is installed.
 
 ```bash
 JAVA_CODEBASE_RAG_RUN_HEAVY=1 .venv/bin/pytest tests -v

tests/test_cli_progress_stdout_invariant.py

@@ -115,6 +115,7 @@ async def communicate(self) -> tuple[bytes, bytes]:
     assert "idx_out" in out.stdout
 
 
+@pytest.mark.skipif(os.environ.get("JAVA_CODEBASE_RAG_RUN_HEAVY", "").strip() != "1", reason="cocoindex lifecycle; set JAVA_CODEBASE_RAG_RUN_HEAVY=1")
 @pytest.mark.skipif(not _cocoindex_available(), reason="cocoindex not installed in venv")
 def test_cli_lifecycle_stdout_invariant_init(corpus_root: Path, tmp_path: Path) -> None:
     baseline = (_FIXTURE_DIR / "init_quiet_success.stdout.txt").read_text(encoding="utf-8")
@@ -197,6 +198,7 @@ def test_cli_lifecycle_stdout_invariant_erase_quiet(tmp_path: Path) -> None:
     assert proc.stdout.strip() == '{"message": "erase completed", "success": true}'
 
 
+@pytest.mark.skipif(os.environ.get("JAVA_CODEBASE_RAG_RUN_HEAVY", "").strip() != "1", reason="cocoindex lifecycle; set JAVA_CODEBASE_RAG_RUN_HEAVY=1")
 @pytest.mark.skipif(not _cocoindex_available(), reason="cocoindex not installed in venv")
 def test_cli_lifecycle_stdout_invariant_init_increment_reprocess_when_cocoindex(
     tmp_path: Path,
@@ -240,3 +242,34 @@ def test_cli_lifecycle_stdout_invariant_init_increment_reprocess_when_cocoindex(
     assert rep_payload.get("success") is True
     assert isinstance(rep_payload.get("stdout"), str)
     assert isinstance(rep_payload.get("graph_stderr"), str)
+
+
+def test_pipeline_footer_reflects_exception_before_propagate(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    from java_codebase_rag.config import resolve_operator_config
+
+    import java_codebase_rag.cli as cli_mod
+
+    cfg = resolve_operator_config(source_root=tmp_path, cli_index_dir=str(tmp_path / "ix_footer"))
+    codes: list[int] = []
+
+    def capture_footer(_sub: str, _t0: float, code: int) -> None:
+        codes.append(code)
+
+    monkeypatch.setattr(cli_mod, "_pipeline_footer", capture_footer)
+
+    def boom() -> int:
+        raise RuntimeError("simulated handler failure")
+
+    with pytest.raises(RuntimeError, match="simulated handler failure"):
+        cli_mod._run_with_pipeline_progress("reprocess", cfg, quiet=False, work=boom)
+    assert codes == [2]
+
+    codes.clear()
+
+    def exit5() -> int:
+        raise SystemExit(5)
+
+    with pytest.raises(SystemExit) as excinfo:
+        cli_mod._run_with_pipeline_progress("reprocess", cfg, quiet=False, work=exit5)
+    assert excinfo.value.code == 5
+    assert codes == [5]

tests/test_cli_quiet_parity.py

@@ -11,6 +11,8 @@
 
 import pytest
 
+from java_codebase_rag import cli as cli_mod
+
 REPO = Path(__file__).resolve().parent.parent
 BUILDER = REPO / "build_ast_graph.py"
 FIXTURE_ROOT = REPO / "tests" / "fixtures" / "call_graph_smoke"
@@ -85,7 +87,6 @@ def test_pipeline_header_footer_present(tmp_path: Path) -> None:
         pytest.skip("java-codebase-rag entrypoint not on PATH")
     idx = tmp_path / "idx_pf"
     idx.mkdir()
-    (idx / "stub.txt").write_text("x", encoding="utf-8")
     env = os.environ.copy()
     env["JAVA_CODEBASE_RAG_INDEX_DIR"] = str(idx)
     env["JAVA_CODEBASE_RAG_SOURCE_ROOT"] = str(tmp_path)
@@ -122,6 +123,8 @@ def test_cli_quiet_stderr_baseline_per_subcommand(tmp_path: Path, corpus_root: P
     assert r_erase.returncode == 0, r_erase.stderr + r_erase.stdout
     _assert_quiet_stderr_no_progress_markers(r_erase.stderr)
 
+    if os.environ.get("JAVA_CODEBASE_RAG_RUN_HEAVY", "").strip() != "1":
+        pytest.skip("cocoindex init/increment/reprocess quiet checks; set JAVA_CODEBASE_RAG_RUN_HEAVY=1")
     if not _cocoindex_available():
         pytest.skip("cocoindex CLI missing — skip init/increment/reprocess quiet checks")
 
@@ -156,7 +159,7 @@ def test_cli_quiet_stderr_baseline_per_subcommand(tmp_path: Path, corpus_root: P
     )
     assert r_inc.returncode == 0, r_inc.stderr + r_inc.stdout
     _assert_quiet_stderr_no_progress_markers(r_inc.stderr)
-    assert "WARNING: AST graph (Kuzu) incremental rebuild is not yet implemented." in r_inc.stderr
+    assert r_inc.stderr == "\n".join(cli_mod._INCREMENT_WARNING_LINES) + "\n"
 
     r_rep = subprocess.run(
         [exe, "reprocess", "--source-root", str(corpus_root), "--index-dir", str(idx_life), "--quiet"],