better-code-review-graph 3.28.0__tar.gz → 3.29.0__tar.gz

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "better-code-review-graph",
   "description": "Knowledge graph for token-efficient code reviews -- semantic search and call-graph resolution across your codebase.",
-  "version": "3.28.0",
+  "version": "3.29.0",
   "userConfig": {
     "EMBEDDING_MODELS": {
       "type": "string",

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 <!-- version list -->
 
+## v3.29.0 (2026-09-27)
+
+### Features
+
+- Rank summarize queue with deterministic order and jev advisory batches
+  ([`2739dd8`](https://github.com/n24q02m/crg/commit/2739dd85386bb6080b97380902e021bc84bd4fba))
+
+
+## v3.28.1 (2026-09-27)
+
+### Bug Fixes
+
+- Enforce no-auth loopback guard against config-sourced host
+  ([#1102](https://github.com/n24q02m/crg/pull/1102),
+  [`bf4afc3`](https://github.com/n24q02m/crg/commit/bf4afc338aa7443959fc522cfa980ef583d7e26d))
+
+
 ## v3.28.0 (2026-09-27)
 
 ### Code Style

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: better-code-review-graph
-Version: 3.28.0
+Version: 3.29.0
 Summary: Token-efficient code review knowledge graph: semantic search and call-graph resolution.
 Author: n24q02m
 License-Expression: Apache-2.0

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "better-code-review-graph"
-version = "3.28.0"
+version = "3.29.0"
 description = "Token-efficient code review knowledge graph: semantic search and call-graph resolution."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/n24q02m/crg.git",
     "source": "github"
   },
-  "version": "3.28.0",
+  "version": "3.29.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "better-code-review-graph",
-      "version": "3.28.0",
+      "version": "3.29.0",
       "runtimeHint": "uvx",
       "runtimeArgs": [
         "--python",

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/src/better_code_review_graph/cli.py

@@ -537,18 +537,21 @@ def _handle_server_start(args: argparse.Namespace) -> int:
     from .server import serve_main
 
     os.environ["MCP_TRANSPORT"] = "http"
-    # run_http() resolves bind address from these (falls back to config).
-    host = args.host or os.environ.get("MCP_HOST")
+    # run_http() bind precedence: MCP_HOST env > settings.server.host; --port
+    # hands off via MCP_PORT (honored at server.py:986-989).
+    settings = load_instance_settings()
     if args.host:
         os.environ["MCP_HOST"] = args.host
     if args.port:
         os.environ["MCP_PORT"] = str(args.port)
     # Security property carried over from the wp2-wip line: an
     # unauthenticated (no-auth) listener must never bind off-loopback.
+    # Resolve the EFFECTIVE bind host the way run_http does.
+    host = args.host or os.environ.get("MCP_HOST") or settings.server.host
     if (
         host
         and host not in {"localhost", "127.0.0.1", "::1"}
-        and load_instance_settings().server.auth == "no-auth"
+        and settings.server.auth == "no-auth"
     ):
         print(
             "crg refuses to start: auth = 'no-auth' only permits loopback "

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/src/better_code_review_graph/docs/graph.md

@@ -148,6 +148,7 @@ graph is unchanged. A provider key alone does not enable summaries.
 **Cost cap + caching:**
 - Default cap is 500 LLM calls per invocation. Tune with `max_nodes` for tighter budgets.
 - Repeat invocations skip nodes whose `source_hash` + full selected model match. `summary_provider` stores the `provider/model` identity, so switching models within one provider invalidates stale summaries too.
+- The work queue has a deterministic base order (`ORDER BY id`). When the host configures a `[models.jev_score]` cell, the pending queue is additionally re-prioritized by one advisory jev call per ~50-node batch (never one call per node); the result carries a `jev_ranking` receipt (`used`, `batches`, `ranked_nodes`, `failopen_reason`). Any jev failure is fail-open: the queue keeps its base order and only the receipt notes it.
 
 **Example:**
 ```json

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/src/better_code_review_graph/summarizer.py

@@ -8,10 +8,15 @@ fallback. The full selected model is persisted in ``summary_provider`` so
 switching models invalidates the cached summary.
 
 Dispatch goes through hull-core's ``OpenAICompatClient`` (async httpx, one
-client per batch). The batch queue keeps its exact historical shape: a
-single ``SELECT ... LIMIT ?`` over Function nodes with no ORDER BY (spec
-§7 K4 — the queue only lines work up; it does not reorder or change the
-schema), capped at ``max_nodes`` per run.
+client per batch). The batch queue is a single ``SELECT ... LIMIT ?`` over
+Function nodes with a deterministic base ordering (``ORDER BY id``, spec
+§7 K4). On top of that base order, an optional jev ranking layer re-orders
+the pending (cache-miss) queue in ~50-node batches — exactly one advisory
+``jev_score`` call per batch, never one call per node — and is strictly
+fail-open: any jev unavailability (cell not configured, call error,
+unparseable reply) leaves the queue in base order and is recorded in the
+run receipt only. The queue never changes the schema, only the processing
+order.
 """
 
 from __future__ import annotations
@@ -19,6 +24,7 @@ from __future__ import annotations
 import asyncio
 import hashlib
 import logging
+import re
 from dataclasses import dataclass
 from typing import Any
 
@@ -81,6 +87,22 @@ def summary_cell() -> Any:
     return cell if cell.configured else None
 
 
+def jev_score_cell() -> Any:
+    """The configured jev_score cell (host-only key), or ``None``.
+
+    Unlike :func:`summary_cell`, resolution failures also yield ``None``:
+    the ranking layer is advisory (spec §7 K4 fail-open), so an unreadable
+    config may only ever disable prioritization, never the queue itself.
+    """
+    try:
+        from .config import resolve_cells
+
+        cell = resolve_cells().get("jev_score")
+    except Exception:  # config problems must only disable ranking
+        return None
+    return cell if cell is not None and cell.configured else None
+
+
 # ---------------------------------------------------------------------------
 # Single-node LLM summarization
 # ---------------------------------------------------------------------------
@@ -144,6 +166,31 @@ def _auth_mode() -> str:
 # Default cap on per-run LLM calls. Override per-call via the max_nodes parameter.
 DEFAULT_MAX_NODES_PER_RUN = 500
 
+# jev ranking layer (spec §7 K4): the pending queue is re-ordered in batches
+# of this many nodes, with exactly one advisory jev_score call per batch.
+JEV_BATCH_SIZE = 50
+
+# Per-node excerpt handed to the ranking call, and the cap on the recorded
+# fail-open reason so a chatty provider error cannot bloat the receipt.
+_JEV_EXCERPT_CHARS = 160
+_FAILOPEN_REASON_MAX_CHARS = 200
+
+
+@dataclass(frozen=True)
+class JevRankingReceipt:
+    """Provenance of the jev ranking layer for one batch_summarize run.
+
+    ``used=True`` means jev re-ordered the queue. ``used=False`` with a
+    ``None`` ``failopen_reason`` means the layer was disabled (no jev cell,
+    or a single-node queue); a non-``None`` reason means jev was attempted,
+    failed, and the queue fell back to base order.
+    """
+
+    used: bool
+    batches: int = 0  # ranked batches; one jev call each
+    ranked_nodes: int = 0  # nodes whose queue position jev decided
+    failopen_reason: str | None = None  # why ranking was skipped, if attempted
+
 
 @dataclass(frozen=True)
 class BatchSummarizeResult:
@@ -154,6 +201,132 @@ class BatchSummarizeResult:
     skipped_no_provider: bool = False  # True iff no chat cell is configured
     provider: str | None = None  # provider used (None if skipped)
     errors: int = 0  # nodes where the chat call raised; counted, batch continues
+    jev_ranking: JevRankingReceipt | None = None  # queue ranking provenance
+
+
+# ---------------------------------------------------------------------------
+# jev queue ranking (spec §7 K4 — advisory, fail-open)
+# ---------------------------------------------------------------------------
+
+_JEV_RANK_PROMPT_PREFIX = (
+    "You are prioritizing a code-review summarization queue. Rank the "
+    "numbered functions below by value to a code reviewer: core logic, "
+    "complex control flow and public entry points first; trivial accessors, "
+    "constants and one-line wrappers last.\n"
+    "Reply with ONLY a JSON array of the indices in priority order, e.g. "
+    "[3, 1, 0, 2]. Every index must appear exactly once.\n\nFunctions:\n"
+)
+
+# Scan the reply for numeric tokens (mnemo-wp4-writer jev precedent:
+# ``[+-]?\\d*\\.\\d+|\\d+``); a reply without any number raises instead of
+# guessing an order.
+_NUMBER_RE = re.compile(r"[+-]?\d*\.\d+|\d+")
+
+
+def _parse_jev_ranking(content: str, batch_size: int) -> list[int]:
+    """Parse jev's priority order out of its reply.
+
+    Follows the mnemo-wp4-writer precedent: scan for numeric tokens, raise
+    when the reply carries no numbers at all. Indices outside
+    ``range(batch_size)`` and duplicates are ignored; an incomplete
+    permutation raises so the caller can fail open to base order.
+    """
+    tokens = _NUMBER_RE.findall(content)
+    if not tokens:
+        raise ValueError(f"jev ranking reply has no numeric tokens: {content[:80]!r}")
+    order: list[int] = []
+    seen: set[int] = set()
+    for token in tokens:
+        index = int(float(token))
+        if 0 <= index < batch_size and index not in seen:
+            seen.add(index)
+            order.append(index)
+    if len(order) != batch_size:
+        raise ValueError(
+            f"jev ranking incomplete: got {len(order)} of {batch_size} indices"
+        )
+    return order
+
+
+async def _jev_rank_batch(
+    client: Any,
+    batch: list[tuple[int, NodeNeedingSummary]],
+) -> list[tuple[int, NodeNeedingSummary]]:
+    """One advisory jev call: return ``batch`` re-ordered by review priority."""
+    listing = _JEV_RANK_PROMPT_PREFIX
+    for position, (_, node) in enumerate(batch):
+        condensed = " ".join(node.source_text.split())[:_JEV_EXCERPT_CHARS]
+        listing += (
+            f"{position}. ({len(node.source_text.splitlines())} lines) {condensed}\n"
+        )
+    content = await client.chat(
+        [{"role": "user", "content": listing}],
+        max_tokens=1024,
+        reasoning={"exclude": True},
+    )
+    order = _parse_jev_ranking(content, len(batch))
+    return [batch[index] for index in order]
+
+
+async def _jev_rank_queue(
+    client: Any,
+    pending: list[tuple[int, NodeNeedingSummary]],
+    batch_size: int = JEV_BATCH_SIZE,
+) -> tuple[list[tuple[int, NodeNeedingSummary]], int]:
+    """Rank the whole pending queue, one jev call per ``batch_size`` chunk.
+
+    Any failure propagates: the caller discards partial rankings and keeps
+    the queue in base order (fail-open is all-or-nothing per run).
+    """
+    ordered: list[tuple[int, NodeNeedingSummary]] = []
+    batches = 0
+    for start in range(0, len(pending), batch_size):
+        batch = pending[start : start + batch_size]
+        ordered.extend(await _jev_rank_batch(client, batch))
+        batches += 1
+    return ordered, batches
+
+
+def _maybe_jev_rank(
+    pending: list[tuple[int, NodeNeedingSummary]],
+) -> tuple[JevRankingReceipt, list[tuple[int, NodeNeedingSummary]]]:
+    """Re-order ``pending`` via the advisory jev ranking layer (spec §7 K4).
+
+    Fail-open: an unconfigured cell returns the queue unchanged silently;
+    any ranking failure logs a warning and returns the queue unchanged with
+    the reason on the receipt. Only a fully successful pass re-orders.
+    """
+    if len(pending) < 2:  # nothing to prioritize
+        return JevRankingReceipt(used=False), pending
+
+    jev_cell = jev_score_cell()
+    if jev_cell is None:
+        return JevRankingReceipt(used=False), pending
+
+    async def _rank() -> tuple[list[tuple[int, NodeNeedingSummary]], int]:
+        client = OpenAICompatClient(jev_cell, auth_mode=_auth_mode())
+        try:
+            return await _jev_rank_queue(client, pending, JEV_BATCH_SIZE)
+        finally:
+            await client.aclose()
+
+    try:
+        ordered, batches = asyncio.run(_rank())
+    except Exception as exc:  # ranking is advisory only — never block the queue
+        logger.warning("jev ranking failed; queue keeps base order: %s", exc)
+        return (
+            JevRankingReceipt(
+                used=False,
+                batches=0,
+                ranked_nodes=0,
+                failopen_reason=str(exc)[:_FAILOPEN_REASON_MAX_CHARS],
+            ),
+            pending,
+        )
+    return (
+        JevRankingReceipt(used=True, batches=batches, ranked_nodes=len(ordered)),
+        ordered,
+    )
 
 
 def batch_summarize(
@@ -165,8 +338,11 @@ def batch_summarize(
 
     Iteration scope: at most ``max_nodes`` Function-kind nodes whose
     ``source_text`` is non-null, selected by one ``SELECT ... LIMIT ?``
-    with no ORDER BY (queue order is the storage engine's row order —
-    spec §7 K4 keeps this exactly). For each candidate:
+    with deterministic base ordering (``ORDER BY id`` — spec §7 K4). When
+    the host configures a jev_score cell, the pending (cache-miss) queue is
+    additionally re-ordered by one advisory jev call per ~50-node batch;
+    any jev failure leaves the queue in base order (fail-open) and is
+    recorded in :attr:`BatchSummarizeResult.jev_ranking`. For each candidate:
 
     - If stored summary + ``summary_provider`` + ``source_hash`` all match
       the selected model + freshly-computed source hash, it's a cache hit
@@ -204,7 +380,8 @@ def batch_summarize(
     # because it copies large `source_text` columns.
     cursor = store._conn.execute(
         "SELECT id, source_text, source_hash, summary, summary_provider FROM nodes "
-        "WHERE kind='Function' AND source_text IS NOT NULL LIMIT ?",
+        "WHERE kind='Function' AND source_text IS NOT NULL "
+        "ORDER BY id LIMIT ?",
         (max_nodes,),
     )
 
@@ -240,6 +417,8 @@ def batch_summarize(
             )
         )
 
+    ranking, pending = _maybe_jev_rank(pending)
+
     if pending:
         generated, errors = asyncio.run(
             _summarize_pending(store, cell, cache_provider, pending)
@@ -253,6 +432,7 @@ def batch_summarize(
         skipped_no_provider=False,
         provider=cache_provider,
         errors=errors,
+        jev_ranking=ranking,
     )
 
 
@@ -264,8 +444,9 @@ async def _summarize_pending(
 ) -> tuple[int, int]:
     """Run the pending queue through one shared hull client.
 
-    Sequential, cursor order preserved. Each failure is logged + counted;
-    the batch continues (fail-open per-node, spec §7).
+    Sequential, queue order preserved (base ``ORDER BY id`` order,
+    optionally re-ranked by the jev layer). Each failure is logged and
+    counted; the batch continues (fail-open per-node, spec §7).
     """
     client = OpenAICompatClient(cell, auth_mode=_auth_mode())
     generated = 0

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/src/better_code_review_graph/tools.py

@@ -16,6 +16,7 @@ import hashlib
 import json
 import logging
 import time
+from dataclasses import asdict
 from pathlib import Path
 from typing import Any
 
@@ -2933,7 +2934,9 @@ def summarize_graph_dispatch(
         max_nodes: Max LLM calls per invocation. Default 500.
 
     Returns:
-        Dict with status, generated, cached, errors, provider, summary.
+        Dict with status, generated, cached, errors, provider, jev_ranking,
+        summary. ``jev_ranking`` carries the queue-ranking receipt (None on
+        the skipped path); see ``summarizer.JevRankingReceipt``.
     """
     from . import summarizer
 
@@ -2962,6 +2965,7 @@ def summarize_graph_dispatch(
         "generated": result.generated,
         "cached": result.cached,
         "errors": result.errors,
+        "jev_ranking": asdict(result.jev_ranking) if result.jev_ranking else None,
         "summary": (
             f"Summarized {result.generated} new + {result.cached} cached Function "
             f"node(s) via {result.provider}"

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/tests/conftest.py

@@ -14,6 +14,20 @@ import pytest
 REAL_HOME = Path.home()
 
 
+@pytest.fixture(autouse=True)
+def _jev_ranking_disabled_by_default(monkeypatch):
+    """Default every test to jev-ranking-off (spec §7 K4).
+
+    Ranking is an advisory layer driven by the host's ``[models.jev_score]``
+    cell; without this opt-out a developer/CI box with that cell configured
+    would leak live jev calls into unrelated queue tests. Tests exercising
+    the ranking layer re-patch ``summarizer.jev_score_cell`` themselves.
+    """
+    monkeypatch.setattr(
+        "better_code_review_graph.summarizer.jev_score_cell", lambda: None
+    )
+
+
 def pytest_addoption(parser):
     """Add --setup and --browser CLI options for E2E tests."""
     parser.addoption("--setup", choices=["relay", "env", "plugin"], default="env")

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/tests/test_cli_control_plane.py

@@ -73,7 +73,13 @@ def test_db_path_prints_graph_db(capsys) -> None:
     assert out.endswith("graph.db")
 
 
-def test_server_start_forces_http_transport(capsys, monkeypatch) -> None:
+def test_server_start_forces_http_transport(capsys, tmp_path, monkeypatch) -> None:
+    cfg = tmp_path / "cfg"
+    cfg.mkdir()
+    (cfg / "config.toml").write_text(
+        '[server]\nhost = "127.0.0.1"\nport = 61000\nauth = "no-auth"\n'
+    )
+    monkeypatch.setenv("CRG_CONFIG_DIR", str(cfg))
     monkeypatch.delenv("MCP_TRANSPORT", raising=False)
     monkeypatch.delenv("MCP_HOST", raising=False)
     monkeypatch.delenv("MCP_PORT", raising=False)
@@ -110,6 +116,7 @@ def test_server_start_refuses_no_auth_off_loopback(
     )
     monkeypatch.setenv("CRG_CONFIG_DIR", str(cfg))
     monkeypatch.delenv("MCP_TRANSPORT", raising=False)
+    monkeypatch.delenv("MCP_HOST", raising=False)
     serve_called = False
 
     def must_not_serve() -> None:
@@ -124,6 +131,32 @@ def test_server_start_refuses_no_auth_off_loopback(
     assert serve_called is False
 
 
+def test_server_start_refuses_no_auth_config_host_off_loopback(
+    capsys, tmp_path, monkeypatch
+) -> None:
+    """Bypass regression: no --host/MCP_HOST, config-sourced host binds."""
+    cfg = tmp_path / "cfg"
+    cfg.mkdir()
+    (cfg / "config.toml").write_text(
+        '[server]\nhost = "0.0.0.0"\nport = 61000\nauth = "no-auth"\n'
+    )
+    monkeypatch.setenv("CRG_CONFIG_DIR", str(cfg))
+    monkeypatch.delenv("MCP_TRANSPORT", raising=False)
+    monkeypatch.delenv("MCP_HOST", raising=False)
+    serve_called = False
+
+    def must_not_serve() -> None:
+        nonlocal serve_called  # noqa: F841
+        serve_called = True  # pragma: no cover
+
+    monkeypatch.setattr("better_code_review_graph.server.serve_main", must_not_serve)
+    rc = _run(capsys, "server", "start")
+    err = capsys.readouterr().err
+    assert rc == 2
+    assert "no-auth" in err and "loopback" in err
+    assert serve_called is False
+
+
 def test_unknown_subcommand_is_rc2(capsys) -> None:
     rc = _run(capsys, "nope")
     err = capsys.readouterr().err

{better_code_review_graph-3.28.0 → better_code_review_graph-3.29.0}/tests/test_summarize_graph_dispatch.py

@@ -5,7 +5,10 @@ from __future__ import annotations
 from unittest.mock import patch
 
 from better_code_review_graph.graph import GraphStore
-from better_code_review_graph.summarizer import BatchSummarizeResult
+from better_code_review_graph.summarizer import (
+    BatchSummarizeResult,
+    JevRankingReceipt,
+)
 from better_code_review_graph.tools import summarize_graph_dispatch
 
 
@@ -40,6 +43,7 @@ def test_dispatch_returns_ok_with_counts_on_success(tmp_path, monkeypatch):
         skipped_no_provider=False,
         provider="gemini",
         errors=0,
+        jev_ranking=JevRankingReceipt(used=False),
     )
 
     with patch("better_code_review_graph.tools._get_store") as mock_get_store:
@@ -59,6 +63,12 @@ def test_dispatch_returns_ok_with_counts_on_success(tmp_path, monkeypatch):
     assert result["generated"] == 3
     assert result["cached"] == 1
     assert result["errors"] == 0
+    assert result["jev_ranking"] == {
+        "used": False,
+        "batches": 0,
+        "ranked_nodes": 0,
+        "failopen_reason": None,
+    }
     assert "3 new" in result["summary"]
     assert "1 cached" in result["summary"]
     assert "gemini" in result["summary"]