Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(mcp): keep the projection a caller asked for ahead of the ones they did not (#2270)
Raghav Chamadiya8a4941ab8322
diff --git a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.pyindex f460d4032..d9c1cafc4 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py@@ -35,8 +35,10 @@ from __future__ import annotationsimport jsonimport logging+import mathimport osfrom collections.abc import Sequence+from dataclasses import dataclassfrom typing import Anyfrom repowise.server.mcp_server._budget.collector import OmissionCollector@@ -164,6 +166,44 @@ def over_budget(return response_chars(response) > budget - headroom+#: A requested collection keeps whichever of these is larger.+REQUESTED_MIN_ROWS = 3+REQUESTED_MIN_SHARE = 0.25+++def entitled_floor(total: int) -> int:+ """Rows a caller-requested collection keeps before anything else sheds."""+ if total <= REQUESTED_MIN_ROWS:+ return total+ return min(total, max(REQUESTED_MIN_ROWS, math.ceil(total * REQUESTED_MIN_SHARE)))+++def shed_stem(key: str) -> str:+ """The response path a shed-order key names, with the ``[]`` form removed."""+ return key[:-2] if key.endswith("[]") else key+++def _rows_to_keep(rows: Any, requested: bool) -> int:+ """Tail-shed floor for one collection: its entitlement, or one row."""+ if not requested or not isinstance(rows, (list, dict)):+ return 1+ return entitled_floor(len(rows))+++@dataclass(frozen=True)+class _ShedLimits:+ """The knobs every key in one :func:`fit_to_budget` pass shares."""++ headroom: int+ char_budget: int | None+ record_counts: bool++ def exceeded(self, response: dict[str, Any]) -> bool:+ return over_budget(+ response, headroom=self.headroom, char_budget=self.char_budget+ )++def fit_to_budget(response: dict[str, Any],order: Sequence[str],@@ -172,6 +212,7 @@ def fit_to_budget(headroom: int = FIT_HEADROOM_CHARS,char_budget: int | None = None,record_counts: bool = False,+ entitled: frozenset[str] | None = None,) -> dict[str, Any]:"""Shed whole blocks named by *order* until *response* fits the budget.@@ -181,12 +222,18 @@ def fit_to_budget(first. Shedding stops the moment the response fits, so an under-budgetresponse — the common case — is untouched.+ *entitled* names stems the caller asked for; their ``[]`` passes stop at+ :func:`entitled_floor` instead of one row. The order still decides when a+ block is reached, and the ceiling still wins.+Drops go to *collector* as expandable ``[repowise#<ref>]`` markers and set``truncated``. Call before the caller's :meth:`OmissionCollector.attach`,which is what ``headroom`` reserves for."""+ limits = _ShedLimits(headroom, char_budget, record_counts)+ requested = entitled or frozenset()for key in order:- if not over_budget(response, headroom=headroom, char_budget=char_budget):+ if not limits.exceeded(response):breakcontainer, _, leaf = key.rpartition(".")target: Any = response@@ -195,16 +242,8 @@ def fit_to_budget(if not isinstance(target, dict):continueif leaf.endswith("[]"):- _shed_tail(- response,- target,- leaf[:-2],- key[:-2],- collector,- headroom,- char_budget,- record_counts,- )+ keep = _rows_to_keep(target.get(leaf[:-2]), shed_stem(key) in requested)+ _shed_tail(response, target, leaf[:-2], key[:-2], collector, limits, keep)elif target.get(leaf):value = target.pop(leaf)collector.add(key, value)@@ -220,19 +259,16 @@ def _shed_tail(leaf: str,label: str,collector: OmissionCollector,- headroom: int,- char_budget: int | None,- record_counts: bool,+ limits: _ShedLimits,+ keep: int = 1,) -> None:- """Drop ranked rows from the tail of ``container[leaf]`` until it fits."""+ """Drop ranked rows from the tail of ``container[leaf]`` down to *keep*."""rows = container.get(leaf)if not isinstance(rows, (list, dict)):returntotal = len(rows)dropped: list[Any] = []- while len(rows) > 1 and over_budget(- response, headroom=headroom, char_budget=char_budget- ):+ while len(rows) > keep and limits.exceeded(response):if isinstance(rows, list):dropped.append(rows.pop())else:@@ -240,7 +276,7 @@ def _shed_tail(dropped.append({name: rows.pop(name)})if dropped:collector.add(label, list(reversed(dropped)))- if record_counts:+ if limits.record_counts:prior_reason = container.get(f"{leaf}_reduced_reason")collection_total = max(total, int(container.get(f"{leaf}_total") or 0)@@ -280,21 +316,24 @@ def _record_reduction(reductions = response.setdefault("_meta", {}).setdefault("reductions", [])- def visit(node: Any, node_path: str) -> None:+ def visit(node: Any, node_path: str, parent: dict[str, Any], name: str) -> None:if isinstance(node, list):+ # An earlier tail-shed may already have trimmed this list and left+ # the population beside it. Reporting len() here would count only+ # what the trim left, not what the caller lost overall.reductions.append({"field": node_path,- "total": len(node),+ "total": max(len(node), int(parent.get(f"{name}_total") or 0)),"emitted": 0,"reason": "response_budget",})elif isinstance(node, dict):- for name, child in node.items():- visit(child, f"{node_path}.{name}")+ for child_name, child in node.items():+ visit(child, f"{node_path}.{child_name}", node, child_name)- visit(value, path)+ visit(value, path, container, field)def _with_budget_reason(prior_reason: Any) -> str:diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.pyindex dfec9c0d8..b8447e519 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py@@ -18,6 +18,7 @@ from repowise.server.mcp_server._budget.budgeter import (effective_char_budget,fit_to_budget,response_chars,+ shed_stem,truncate_to_budget,)from repowise.server.mcp_server._budget.collector import OmissionCollector@@ -45,6 +46,16 @@ class ResponseBudgetContract:#: uncounted rather than proven absent, so the count is a lower bound.#: A ``<field>_total`` name here is also read as a reduction total.floor_fields: tuple[str, ...] = ()+ #: ``(request token, shed-order keys)``. The token is an ``include`` value+ #: or an argument whose presence is itself the request. Keys named here+ #: shed last and trim to :func:`entitled_floor`; the ceiling still wins, so+ #: this is priority, not immunity. Declaring nothing keeps a tool's+ #: existing behaviour.+ requested_projections: tuple[tuple[str, tuple[str, ...]], ...] = ()+++#: Arguments whose presence asks for the projection that answers them.+_IMPLICIT_REQUEST_ARGUMENTS = ("query", "id", "reference", "changed_files", "targets")#: What a tool gets when it declares no priority of its own. An empty shed@@ -77,6 +88,22 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"impact_surface_total","co_change_partners_total",),+ requested_projections=(+ (+ "changed_files",+ (+ "directive.test_recommendations[]",+ "directive.tests_to_run[]",+ "directive.may_break[]",+ "pr_blast_radius",+ "pr_blast_radius.guarding_tests",+ ),+ ),+ # targets is required, so it is always asked for. Without this the+ # deferred PR blocks jump ahead of it and the rows the caller+ # named become the first thing trimmed.+ ("targets", ("targets[]",)),+ ),),"get_change_risk": ResponseBudgetContract("blocks",@@ -113,6 +140,7 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"retrieval[]","retrieval","code_rationale",+ "quotes[]","quotes","symbol_bodies[]","symbol_bodies",@@ -125,6 +153,20 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {),expansion_argument="include",protected=("answer", "confidence", "citations", "next_action_hint", "degraded"),+ requested_projections=(+ (+ "evidence",+ (+ "retrieval[]",+ "retrieval",+ "symbol_bodies[]",+ "symbol_bodies",+ "quotes[]",+ "quotes",+ "code_rationale",+ ),+ ),+ ),),# Whole-block drops served 0 of 50 pages, 0 of 12 episodes and 0 of 58# mined rationale comments across the two modes. Trimming runs to@@ -162,6 +204,21 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"candidates","origin_story",),+ requested_projections=(+ (+ "query",+ (+ "decisions[]",+ "candidates[]",+ "history[]",+ "related_documentation[]",+ "code_rationale[]",+ "episodes[]",+ ),+ ),+ ("id", ("decisions[]",)),+ ("reference", ("decisions[]",)),+ ),expansion_argument=None,protected=("mode",@@ -188,6 +245,9 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"knowledge_map","key_decisions","outline_hint",+ # Trim the sections before dropping the block: shed as one unit it+ # served 0 of 40 while 73% of the budget went unspent.+ "outline.sections[]","outline","tool_surface","repos[]",@@ -195,6 +255,15 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"content_md",),protected=("title", "architecture", "entry_points"),+ requested_projections=(+ ("outline", ("outline.sections[]", "outline", "outline_hint")),+ ("tour", ("guided_tour", "guided_tour_hint", "reading_order",+ "reading_order_hint")),+ ("decisions", ("key_decisions",)),+ ("graph", ("community_summary",)),+ ("ownership", ("knowledge_map",)),+ ("content", ("content_md",)),+ ),),"get_health": ResponseBudgetContract("blocks",@@ -267,7 +336,7 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {# metadata that followed added roughly 2.6k."search_codebase": ResponseBudgetContract("blocks",- ("candidates", "results[]"),+ ("candidates[]", "candidates", "results[]"),expansion_argument=None,protected=("results", "mode", "exact_match"),),@@ -378,6 +447,63 @@ def _call_uses_expansion(return bool(bound.arguments.get(contract.expansion_argument))+def _include_tokens(value: Any) -> set[str]:+ """Normalise an ``include`` argument to a set of tokens.++ This layer sits outside the failure shield, so anything the caller can+ send has to come back as a set rather than an exception.+ """+ if isinstance(value, str):+ return {value}+ if isinstance(value, (list, tuple, set, frozenset)):+ return {str(token) for token in value}+ return set()+++def _requested_shed_keys(+ contract: ResponseBudgetContract,+ signature: inspect.Signature,+ args: tuple[Any, ...],+ kwargs: dict[str, Any],+) -> frozenset[str]:+ """Shed-order stems this particular call asked for."""+ if not contract.requested_projections:+ return frozenset()+ try:+ bound = dict(signature.bind_partial(*args, **kwargs).arguments)+ except TypeError:+ bound = dict(kwargs)++ asked = _include_tokens(bound.get("include"))+ asked.update(name for name in _IMPLICIT_REQUEST_ARGUMENTS if bound.get(name))++ keys: set[str] = set()+ for token, paths in contract.requested_projections:+ if token in asked:+ keys.update(shed_stem(path) for path in paths)+ return frozenset(keys)+++def _prioritised_shed_order(+ order: tuple[str, ...], requested: frozenset[str]+) -> tuple[str, ...]:+ """Move what the caller asked for to the back of the shed order.++ Within that tail every trimmable key runs before any whole-block drop, so+ two requested blocks cannot end with one trimmed to its floor and the+ other dropped entirely. Relative order is otherwise preserved.+ """+ if not requested:+ return order+ deferred = tuple(key for key in order if shed_stem(key) in requested)+ if not deferred:+ return order+ kept = tuple(key for key in order if shed_stem(key) not in requested)+ trimmable = tuple(key for key in deferred if key.endswith("[]"))+ whole = tuple(key for key in deferred if not key.endswith("[]"))+ return kept + trimmable + whole++def _stamp_accounting(result: dict[str, Any], *, limit: int, tier: str) -> None:meta = result.setdefault("_meta", {})budget = meta.setdefault("response_budget", {})@@ -487,6 +613,7 @@ def _emergency_fit(contract: ResponseBudgetContract,collector: OmissionCollector,limit: int,+ requested: frozenset[str] = frozenset(),) -> None:"""Bound an unexpectedly huge protected core without a false fit claim."""protected = {*contract.protected, "_meta"}@@ -497,7 +624,12 @@ def _emergency_fit(and key not in {"truncated", "omission_marker"}and not key.endswith(("_total", "_emitted", "_reduced_reason"))]- for key in sorted(removable, key=lambda item: response_chars(result[item]), reverse=True):+ # Biggest first, but never a requested block while an unrequested one is+ # still there to drop.+ def order(item: str) -> tuple[bool, int]:+ return (item in requested, -response_chars(result[item]))++ for key in sorted(removable, key=order):if response_chars(result) <= limit:returnvalue = result.pop(key)@@ -617,6 +749,7 @@ def enforce_response_budget(collector = OmissionCollector(tool, repo_root=repo_root)headroom = min(_FINAL_HEADROOM_CHARS, max(100, limit // 4))working_limit = max(1, limit - headroom)+ requested = _requested_shed_keys(contract, signature, args, kwargs)if contract.strategy == "targets":truncate_to_budget(result,@@ -627,18 +760,19 @@ def enforce_response_budget(else:fit_to_budget(result,- contract.shed_order,+ _prioritised_shed_order(contract.shed_order, requested),collector,char_budget=working_limit,headroom=0,record_counts=True,+ entitled=requested,)run_post_shed(tool, result, collector)collector.attach(result)if response_chars(result) > limit:emergency = OmissionCollector(tool, repo_root=repo_root)- _emergency_fit(result, contract, emergency, working_limit)+ _emergency_fit(result, contract, emergency, working_limit, requested)emergency.attach(result)run_post_enforce(tool, result)diff --git a/tests/unit/server/mcp/test_requested_projection_priority.py b/tests/unit/server/mcp/test_requested_projection_priority.pynew file mode 100644index 000000000..e5640027b--- /dev/null+++ b/tests/unit/server/mcp/test_requested_projection_priority.py@@ -0,0 +1,228 @@+"""What the caller asked for sheds last, and trims instead of vanishing."""++from __future__ import annotations++import inspect+from typing import Any++import pytest++from repowise.server.mcp_server._budget import enforce_response_budget+from repowise.server.mcp_server._budget.budgeter import entitled_floor, shed_stem+from repowise.server.mcp_server._budget.contracts import (+ _CONTRACTS,+ ResponseBudgetContract,+ _prioritised_shed_order,+ _requested_shed_keys,+)+++def _overview_signature() -> inspect.Signature:+ def get_overview(repo: str | None = None, include: list[str] | None = None): ...++ return inspect.signature(get_overview)+++def _overview_payload(sections: int = 40) -> dict[str, Any]:+ return {+ "title": "Repository Overview",+ "architecture": {"layers": []},+ "entry_points": [],+ "outline": {+ "sections": [+ {"title": f"section {i}", "body": "x" * 900} for i in range(sections)+ ]+ },+ "content_md": "y" * 4000,+ "key_modules": [{"name": f"module {i}"} for i in range(30)],+ "tool_surface": {+ "tools": [{"name": f"tool {i}", "description": "z" * 200} for i in range(11)]+ },+ "_meta": {"contract_version": 1},+ }+++def _enforce(tool: str, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:+ return enforce_response_budget(+ tool,+ payload,+ signature=_overview_signature(),+ args=(),+ kwargs=kwargs,+ repo_root=None,+ )+++ ("total", "expected"),+ [(0, 0), (1, 1), (3, 3), (4, 3), (12, 3), (40, 10), (400, 100)],+)+def test_entitled_floor_never_exceeds_population(total: int, expected: int) -> None:+ assert entitled_floor(total) == expected+++def test_requested_outline_survives_and_spends_the_budget() -> None:+ result = _enforce("get_overview", _overview_payload(), include=["outline"])++ sections = result["outline"]["sections"]+ budget = result["_meta"]["response_budget"]+ assert len(sections) >= entitled_floor(40)+ # The regression was 0 of 40 served while 73% of the budget went unspent.+ assert budget["serialized_chars"] > budget["limit_chars"] * 0.75+++def test_asking_for_a_block_keeps_more_of_it_than_not_asking() -> None:+ """Entitlement is not a licence to keep everything on every call."""+ asked = _enforce("get_overview", _overview_payload(), include=["outline"])+ unasked = _enforce("get_overview", _overview_payload())++ kept = len(asked["outline"]["sections"])+ incidental = len((unasked.get("outline") or {}).get("sections", []))+ assert kept > incidental+ assert unasked["truncated"] is True+++def test_requested_block_outlives_unrequested_ones() -> None:+ result = _enforce("get_overview", _overview_payload(), include=["outline"])++ assert result["outline"]["sections"]+ assert "community_summary" not in result+++def test_trimmed_requested_collection_keeps_recoverable_counts() -> None:+ result = _enforce("get_overview", _overview_payload(), include=["outline"])+ outline = result["outline"]++ if outline.get("sections_truncated"):+ assert outline["sections_total"] == 40+ assert outline["sections_emitted"] == len(outline["sections"])+ assert outline["sections_omitted"] == 40 - len(outline["sections"])+ assert result["_meta"]["omitted"]["refs"]+++def test_response_still_obeys_the_hard_ceiling() -> None:+ """A requested projection may be trimmed; it may not burst the ceiling."""+ result = _enforce("get_overview", _overview_payload(sections=4000), include=["outline"])++ budget = result["_meta"]["response_budget"]+ assert budget["serialized_chars"] <= budget["limit_chars"]+++def test_declaring_nothing_leaves_the_shed_order_alone() -> None:+ contract = ResponseBudgetContract("blocks", ("a", "b[]", "c"))+ requested = _requested_shed_keys(+ contract, _overview_signature(), (), {"include": ["a"]}+ )++ assert requested == frozenset()+ assert _prioritised_shed_order(contract.shed_order, requested) == ("a", "b[]", "c")+++def test_priority_defers_requested_keys_and_keeps_relative_order() -> None:+ order = ("a", "b[]", "c", "d")++ assert _prioritised_shed_order(order, frozenset({"b", "c"})) == ("a", "d", "b[]", "c")+++def test_every_requested_trim_runs_before_any_requested_whole_drop() -> None:+ """Two requested blocks must not end with one trimmed and one deleted."""+ order = ("x", "tour", "outline.sections[]", "outline")++ assert _prioritised_shed_order(order, frozenset({"tour", "outline.sections", "outline"})) == (+ "x",+ "outline.sections[]",+ "tour",+ "outline",+ )+++def test_a_non_iterable_include_does_not_raise() -> None:+ """This layer sits outside the failure shield."""+ contract = ResponseBudgetContract(+ "blocks", ("a[]",), requested_projections=(("z", ("a[]",)),)+ )++ assert _requested_shed_keys(+ contract, _overview_signature(), (), {"include": 5}+ ) == frozenset()+++def test_risk_targets_are_not_trimmed_ahead_of_pr_blocks() -> None:+ """targets is required, so PR mode must not shed it first."""+ def get_risk(+ targets: list[str],+ repo: str | None = None,+ changed_files: list[str] | None = None,+ include: list[str] | None = None,+ ): ...++ requested = _requested_shed_keys(+ _CONTRACTS["get_risk"],+ inspect.signature(get_risk),+ (),+ {"targets": ["a.py"], "changed_files": ["a.py"]},+ )+ order = _prioritised_shed_order(_CONTRACTS["get_risk"].shed_order, requested)++ # Ambient repo-wide context goes before anything the caller named, and+ # target rows keep their entitlement rather than collapsing to one.+ assert order.index("global_hotspots") < order.index("targets[]")+ assert "targets" in requested+++def test_a_trimmed_then_dropped_block_reports_the_whole_population() -> None:+ """outline.sections[] trims, then outline is dropped: totals must survive."""+ payload = _overview_payload()+ outline = payload["outline"]+ outline["sections"] = outline["sections"][:10]+ outline["sections_total"] = 40+ outline["sections_emitted"] = 10++ result = enforce_response_budget(+ "get_overview",+ {**payload, "content_md": "y" * 40_000},+ signature=_overview_signature(),+ args=(),+ kwargs={},+ repo_root=None,+ )++ rows = [+ row+ for row in result["_meta"].get("reductions", [])+ if row["field"] == "outline.sections"+ ]+ if rows:+ assert rows[0]["total"] == 40+++def test_query_mode_counts_as_a_request() -> None:+ def get_why(query: str | None = None, targets: list[str] | None = None): ...++ requested = _requested_shed_keys(+ _CONTRACTS["get_why"], inspect.signature(get_why), (), {"query": "why JWT?"}+ )++ assert "decisions" in requested+ assert "episodes" in requested+++def test_no_query_asks_for_nothing() -> None:+ def get_why(query: str | None = None, targets: list[str] | None = None): ...++ requested = _requested_shed_keys(+ _CONTRACTS["get_why"], inspect.signature(get_why), (), {"targets": ["a.py"]}+ )++ assert requested == frozenset()++[email protected]("tool", sorted(_CONTRACTS))+def test_declared_projections_name_real_shed_order_keys(tool: str) -> None:+ """A projection mapping a key the shed order lacks silently does nothing."""+ contract = _CONTRACTS[tool]+ stems = {shed_stem(key) for key in contract.shed_order}++ for token, paths in contract.requested_projections:+ for path in paths:+ assert shed_stem(path) in stems, f"{tool}: {token} -> {path}"