address review: extract _hints_or_skip helper, add test coverage

- Deduplicate 5 inline ternaries into _hints_or_skip() helper
- Add test_hints_enabled_defaults_to_true and
  test_hints_enabled_env_over_yaml_over_default for config precedence
- Add test_hints_or_skip_skips_when_disabled to verify gating

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: HumanBean17

mcp_v2.py

@@ -42,6 +42,10 @@ def set_hints_enabled(enabled: bool) -> None:
     global _hints_enabled
     _hints_enabled = enabled
 
+
+def _hints_or_skip(tool: str, payload: dict) -> tuple[list, list]:
+    return generate_hints(tool, payload) if _hints_enabled else ([], [])
+
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
 
 # Stored graph edge labels for one-hop neighbors. Composed DECLARES.* and OVERRIDDEN_BY.*
@@ -945,9 +949,7 @@ def search_v2(
             "limit": limit,
             "offset": offset,
         }
-        raw_struct, raw_advisories = (
-            generate_hints("search", hint_payload) if _hints_enabled else ([], [])
-        )
+        raw_struct, raw_advisories = _hints_or_skip("search", hint_payload)
         return SearchOutput(
             success=True,
             results=hits,
@@ -1038,9 +1040,7 @@ def find_v2(
             "filter": filter_dump,
             "has_more_results": has_more_results,
         }
-        raw_struct, raw_advisories = (
-            generate_hints("find", hint_payload) if _hints_enabled else ([], [])
-        )
+        raw_struct, raw_advisories = _hints_or_skip("find", hint_payload)
         return FindOutput(
             success=True,
             results=refs,
@@ -1120,10 +1120,7 @@ def describe_v2(
                         f"java-codebase-rag unresolved-calls list --method-id {node_id} for the full list"
                     )
         record = NodeRecord(id=ref.id, kind=kind, fqn=ref.fqn, data=data, edge_summary=edge_summary)
-        raw_struct, raw_advisories = (
-            generate_hints("describe", {"success": True, "record": record.model_dump()})
-            if _hints_enabled else ([], [])
-        )
+        raw_struct, raw_advisories = _hints_or_skip("describe", {"success": True, "record": record.model_dump()})
         return DescribeOutput(
             success=True,
             record=record,
@@ -1453,9 +1450,7 @@ def _resolve_finalize_success(
         "path_prefix_seed": path_prefix_seed,
         "target_service_seed": target_service_seed,
     }
-    raw_struct, raw_advisories = (
-        generate_hints("resolve", hint_payload) if _hints_enabled else ([], [])
-    )
+    raw_struct, raw_advisories = _hints_or_skip("resolve", hint_payload)
     out = out.model_copy(update={
         "advisories": raw_advisories,
         "hints_structured": _to_structured_hints(raw_struct),
@@ -1989,9 +1984,7 @@ def neighbors_v2(
             "unresolved_count": unresolved_count,
             "calls_row_count": calls_row_count,
         }
-        raw_struct, raw_advisories = (
-            generate_hints("neighbors", neigh_payload) if _hints_enabled else ([], [])
-        )
+        raw_struct, raw_advisories = _hints_or_skip("neighbors", neigh_payload)
         return NeighborsOutput(
             success=True,
             results=sliced,

tests/test_java_codebase_rag_cli.py

@@ -223,6 +223,31 @@ def test_embedding_device_precedence_cli_over_env_over_yaml_over_default(
     assert r3.embedding_device == "cpu"
 
 
+def test_hints_enabled_defaults_to_true(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("JAVA_CODEBASE_RAG_HINTS_ENABLED", raising=False)
+    r = resolve_operator_config(source_root=tmp_path)
+    assert r.hints_enabled is True
+    assert r.hints_enabled_source == "default"
+
+
+def test_hints_enabled_env_over_yaml_over_default(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("JAVA_CODEBASE_RAG_HINTS_ENABLED", raising=False)
+    (tmp_path / ".java-codebase-rag.yml").write_text(
+        "hints:\n  enabled: false\n", encoding="utf-8",
+    )
+    r = resolve_operator_config(source_root=tmp_path)
+    assert r.hints_enabled is False
+    assert r.hints_enabled_source == "yaml"
+    monkeypatch.setenv("JAVA_CODEBASE_RAG_HINTS_ENABLED", "1")
+    r2 = resolve_operator_config(source_root=tmp_path)
+    assert r2.hints_enabled is True
+    assert r2.hints_enabled_source == "env"
+
+
 def test_yaml_config_ignores_legacy_filename_reads_new_filename(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
 ) -> None:

tests/test_mcp_hints.py

@@ -17,6 +17,8 @@
 from mcp_v2 import (
     FindOutput,
     SearchOutput,
+    _hints_or_skip,
+    set_hints_enabled,
     describe_v2,
     find_v2,
     neighbors_v2,
@@ -1307,3 +1309,14 @@ def test_advisories_char_cap() -> None:
     _, advisories = generate_hints("neighbors", payload)
     for a in advisories:
         assert len(a) <= 200, f"advisory too long: {a!r}"
+
+
+def test_hints_or_skip_skips_when_disabled() -> None:
+    """_hints_or_skip returns empty lists and never calls generate_hints when disabled."""
+    set_hints_enabled(False)
+    try:
+        struct, advisories = _hints_or_skip("search", {"success": True, "results": []})
+        assert struct == []
+        assert advisories == []
+    finally:
+        set_hints_enabled(True)  # restore default for other tests