Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(health): count a language-gated unit once in queue counts (#3667)

Swati Ahujafca09dbbb6fb
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 87893e2ef..68791e222 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -329,7 +329,7 @@ One ranked queue across refactoring, performance and code-shape work, the same o
| `lead` | The queue's first item, whatever page `items` is, with its `next_call` |
| `items` | Up to five. With `only=["fix_first"]` the list pages from `cursor` and `recovery.fix_first` names the next page; a passed `limit` sets the page size, up to 25. Each: `id`, `tier`, `kind`, `title`, `target`, `why`, `gain`, `effort`, `confidence`; a `now` or `next` `lead` also carries `first_step` (`action`, `line`, and `file` when it is not the target's) and `verify` (`command`, or `prerequisite` when no test reaches it); with `only=["fix_first"]` the other due items among a page's first five carry them too. `get_health(fix_id=...)` returns one in full, with its `next_call` |
| `items_total`, `cursor` | The eligible items `items` was cut from, and where the page starts |
-| `counts` | `inventory` (every unit considered), `in_scope` (less units excluded for where the code lives: `test`, `tooling`, `generated`, `vendored`, `docs_example`), `eligible` (became an item), `due` (eligible items in tier `now` or `next`), `shown` (items in this response), `excluded` (every non-zero exclusion, by reason) |
+| `counts` | `inventory` (every unit considered), `in_scope` (less units excluded for where the code lives: `test`, `tooling`, `generated`, `vendored`, `docs_example`), `eligible` (became an item), `due` (eligible items in tier `now` or `next`), `shown` (items in this response), `excluded` (every non-zero exclusion, by reason), `gated` (units a language gate holds back, counted in `inventory` only; always 0 here, since Fix first applies no gate) |
| `tier` | `now` (worth doing, safe to start), `next` (worth doing, needs judgment), `later` |
| `kind` | `refactor` (one file's composed refactoring), `perf_fix` (one intervention with its sinks), `finding` (a code-shape finding with no plan) |
| `totals` | `candidates`, `eligible`, `shown`, and `dormant`: distinct functions kept out as `gated_off`. The exclusions by reason are in `counts.excluded` (`gated_off`: a constant flag in the same file switches the function off; `unreachable`: sure dead code, delete it) |
diff --git a/packages/core/src/repowise/core/analysis/health/queue/counts.py b/packages/core/src/repowise/core/analysis/health/queue/counts.py
index 8a658d1dc..278b40b55 100644
--- a/packages/core/src/repowise/core/analysis/health/queue/counts.py
+++ b/packages/core/src/repowise/core/analysis/health/queue/counts.py
@@ -5,7 +5,8 @@ counts at five levels: ``inventory`` every open unit; ``in_scope`` those whose
code is in scope (not test, tooling, vendored, generated or docs); ``eligible``
those a default queue holds; ``due`` eligible units in a tier worth scheduling
now; ``shown`` what the response carries. ``excluded`` names every reason a
-unit is out, so the levels add up.
+unit is out, and ``gated`` counts the units a language gate holds back, so the
+levels add up: ``inventory`` is the served units plus ``gated``.
"""
from __future__ import annotations
@@ -76,6 +77,7 @@ class QueueCounts:
due: int = 0
shown: int = 0
excluded: dict[str, int] = field(default_factory=dict)
+ gated: int = 0
def as_dict(self) -> dict[str, Any]:
return {
@@ -85,12 +87,16 @@ class QueueCounts:
"due": self.due,
"shown": self.shown,
"excluded": dict(self.excluded),
+ "gated": self.gated,
}
-def queue_counts(groups: Iterable[tuple[str | None, str | None, int]], shown: int) -> QueueCounts:
- """Fold ``(reason, tier, n)`` groups (``reason`` ``None`` for an eligible
- unit) into the counts; ``shown`` is the caller's."""
+def queue_counts(
+ groups: Iterable[tuple[str | None, str | None, int]], shown: int, *, gated: int = 0
+) -> QueueCounts:
+ """Fold ``(reason, tier, n)`` groups of served units (``reason`` ``None``
+ for an eligible unit) into the counts; ``shown`` is the caller's and
+ ``gated`` the units a language gate held back."""
eligible = due = 0
excluded: dict[str, int] = {}
for reason, level, n in groups:
@@ -99,21 +105,25 @@ def queue_counts(groups: Iterable[tuple[str | None, str | None, int]], shown: in
due += n if level in DUE_TIERS else 0
else:
excluded[reason] = excluded.get(reason, 0) + n
- return counts_of(eligible, due, excluded, shown)
+ return counts_of(eligible, due, excluded, shown, gated=gated)
-def counts_of(eligible: int, due: int, excluded: Mapping[str, int], shown: int) -> QueueCounts:
- """The counts from what a queue holds and what it left out, by reason."""
+def counts_of(
+ eligible: int, due: int, excluded: Mapping[str, int], shown: int, *, gated: int = 0
+) -> QueueCounts:
+ """The counts from what a queue holds and what it left out, by reason.
+ A gated unit is in ``inventory`` and ``gated`` only."""
kept = {reason: n for reason, n in excluded.items() if n}
- inventory = eligible + sum(kept.values())
+ served = eligible + sum(kept.values())
out_of_scope = sum(n for reason, n in kept.items() if reason in SCOPE_EXCLUSIONS)
return QueueCounts(
- inventory=inventory,
- in_scope=inventory - out_of_scope,
+ inventory=served + gated,
+ in_scope=served - out_of_scope,
eligible=eligible,
due=due,
shown=shown,
excluded=dict(sorted(kept.items(), key=lambda i: (-i[1], i[0]))),
+ gated=gated,
)
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/queue_counts.py b/packages/core/src/repowise/core/persistence/crud/analysis/queue_counts.py
index 9154ffb86..f3eec89f3 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/queue_counts.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/queue_counts.py
@@ -14,6 +14,7 @@ from typing import Any, Literal, get_args
from sqlalchemy import func, select, true
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.finding_registry import GateLayer
from repowise.core.analysis.health.perf.opportunities import PERFORMANCE_MODEL_VERSION
from repowise.core.analysis.health.queue.counts import NOT_JUDGED, QueueCounts, queue_counts
@@ -25,6 +26,7 @@ from .fix_first import (
stored_item_counts,
unjudged,
)
+from .shown import gated_counts, ungated
Unit = Literal["findings", "causes", "plans", "items"]
#: One noun per unit, in the order surfaces list them.
@@ -33,6 +35,14 @@ UNITS: tuple[Unit, ...] = get_args(Unit)
JudgedUnit = Literal["findings", "causes", "plans"]
+#: The gate layer and gated-kind column of each judged unit's rows.
+_GATE_LAYERS: dict[str, tuple[GateLayer, str]] = {
+ "findings": ("health", "biomarker_type"),
+ "causes": ("performance", "biomarker_type"),
+ "plans": ("refactoring", "lead_refactoring_type"),
+}
+
+
def _population(unit: str, repo_id: str) -> tuple[Any, Any]:
if unit == "findings":
return HealthFinding, queue_findings(repo_id)
@@ -59,13 +69,16 @@ async def unit_counts(
*,
shown: int = 0,
file_paths: Sequence[str] | None = None,
+ include_unverified: bool = False,
) -> QueueCounts:
"""``unit``'s counts over its open inventory, in ``file_paths`` when named.
List filters (type, effort, context) never narrow these: the counts say
where a list sits in the whole queue, and ``shown`` is what it carries.
- Fix first items are counted over the whole repository only: their
- exclusions carry no file, so ``file_paths`` is refused for them.
+ Rows a language gate holds back count once, in ``gated``, unless
+ ``include_unverified`` serves them. Fix first items are counted over the
+ whole repository only: their exclusions carry no file, so ``file_paths``
+ is refused for them, and no gate applies to them.
"""
if unit == "items":
if file_paths is not None:
@@ -79,27 +92,50 @@ async def unit_counts(
return (await load_fix_first(session, repo_id, limit=None)).counts(shown)
model, population = _population(unit, repo_id)
scoped = model.file_path.in_(list(file_paths)) if file_paths is not None else true()
+ layer, kind = _GATE_LAYERS[unit]
+ kind_col = getattr(model, kind)
+ served = ungated(layer, model.file_path, kind_col, include_unverified=include_unverified)
rows = await session.execute(
select(model.queue_eligible, model.queue_reason, model.queue_tier, func.count())
- .where(population, scoped)
+ .where(population, scoped, served)
.group_by(model.queue_eligible, model.queue_reason, model.queue_tier)
)
+ gated = await gated_counts(
+ session,
+ layer,
+ model,
+ population,
+ scoped,
+ kind_col=kind_col,
+ include_unverified=include_unverified,
+ )
return queue_counts(
(
(NOT_JUDGED if eligible is None else None if eligible else reason, tier, n)
for eligible, reason, tier, n in rows.all()
),
shown,
+ gated=sum(cell["count"] for cell in gated.values()),
)
async def all_unit_counts(
- session: AsyncSession, repo_id: str, *, shown: dict[str, int] | None = None
+ session: AsyncSession,
+ repo_id: str,
+ *,
+ shown: dict[str, int] | None = None,
+ include_unverified: bool = False,
) -> dict[str, dict[str, Any]]:
"""Every unit's counts, by noun, for a surface that reports them together."""
out: dict[str, dict[str, Any]] = {}
for unit in UNITS:
- counts = await unit_counts(session, repo_id, unit, shown=(shown or {}).get(unit, 0))
+ counts = await unit_counts(
+ session,
+ repo_id,
+ unit,
+ shown=(shown or {}).get(unit, 0),
+ include_unverified=include_unverified,
+ )
out[unit] = counts.as_dict()
return out
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/loading.py b/packages/server/src/repowise/server/mcp_server/tool_health/loading.py
index 6d6a2ba8e..b94d38de1 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/loading.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/loading.py
@@ -184,7 +184,13 @@ async def load_health_data(
)
data.fix_first, data.fix_first_full = await _read_fix_first(session, repository, pop, req)
if "top_findings" in req.only_set and not pop.nothing_resolved:
- counts = await unit_counts(session, repository.id, "findings", file_paths=pop.target_paths)
+ counts = await unit_counts(
+ session,
+ repository.id,
+ "findings",
+ file_paths=pop.target_paths,
+ include_unverified=req.include_unverified,
+ )
data.finding_counts = counts.as_dict()
data.gated = await _read_gated(session, req, data)
return data
diff --git a/packages/server/src/repowise/server/routers/code_health/overview_routes.py b/packages/server/src/repowise/server/routers/code_health/overview_routes.py
index 3415cc802..ffcc853fc 100644
--- a/packages/server/src/repowise/server/routers/code_health/overview_routes.py
+++ b/packages/server/src/repowise/server/routers/code_health/overview_routes.py
@@ -163,7 +163,10 @@ async def health_overview(
# same numbers the lists, MCP and the CLI report, whatever scope or
# counts this page projects.
"queue_counts": await all_unit_counts(
- session, repo_id, shown={"findings": len(top_findings)}
+ session,
+ repo_id,
+ shown={"findings": len(top_findings)},
+ include_unverified=include_unverified,
),
"meta": {
"last_indexed_at": last_indexed_at,
diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.py
index 2094232ec..46f0fd5ad 100644
--- a/packages/server/src/repowise/server/services/performance_health.py
+++ b/packages/server/src/repowise/server/services/performance_health.py
@@ -150,6 +150,7 @@ class PerformanceHealthService:
"causes",
shown=len(items),
file_paths=query.file_paths,
+ include_unverified=self._include_unverified,
)
).as_dict(),
gated=await self.gated(),
diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.py
index a90f210c5..39ecdeb87 100644
--- a/packages/server/src/repowise/server/services/refactoring_health.py
+++ b/packages/server/src/repowise/server/services/refactoring_health.py
@@ -335,6 +335,7 @@ class RefactoringHealthService:
"plans",
shown=shown,
file_paths=query.file_paths,
+ include_unverified=self._include_unverified,
)
return counts.as_dict()
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index f51133868..70855d77b 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -2727,6 +2727,7 @@ export interface QueueCounts {
due?: number;
shown?: number;
excluded?: Record<string, number>;
+ gated?: number;
}
/** What the ``fix_first`` scope leaves out of a page's filtered set. */
diff --git a/packages/types/src/queue.ts b/packages/types/src/queue.ts
index 033f44c42..a85cf5ee0 100644
--- a/packages/types/src/queue.ts
+++ b/packages/types/src/queue.ts
@@ -47,7 +47,8 @@ export type QueueUnit = "findings" | "causes" | "plans" | "items";
* `inventory` every open unit; `in_scope` those whose code is in scope (not
* test, tooling, vendored, generated or docs); `eligible` those a default
* queue holds; `due` eligible units in tier now or next; `shown` what the
- * response carries; `excluded` the non-zero reasons, so the levels add up.
+ * response carries; `excluded` the non-zero reasons; `gated` the units a
+ * language gate holds back, counted there only, so the levels add up.
*/
export interface QueueCounts {
inventory: number;
@@ -56,6 +57,7 @@ export interface QueueCounts {
due: number;
shown: number;
excluded: Partial<Record<QueueReason, number>>;
+ gated: number;
}
/** Every unit's counts, by noun (`queue_counts` on the health overview and `repowise health --format json`). */
diff --git a/tests/unit/health/test_queue_counts.py b/tests/unit/health/test_queue_counts.py
index b75f68a24..ddb9db81f 100644
--- a/tests/unit/health/test_queue_counts.py
+++ b/tests/unit/health/test_queue_counts.py
@@ -37,6 +37,7 @@ def test_the_levels_add_up_and_scope_reasons_leave_in_scope() -> None:
"due": 2,
"shown": 2,
"excluded": {"test": 4, "below_min_worth": 1, "not_judged": 1},
+ "gated": 0,
}
excluded = {"test": 4, "below_min_worth": 1, "not_judged": 1, "tooling": 0}
assert counts_of(5, 2, excluded, 2) == counts
@@ -118,3 +119,18 @@ def test_unaudited_steps_stay_in_the_plan_not_the_item() -> None:
assert ("steps held back", "2 (move or extract-class, not yet audited; in the full plan)") in {
(f.label, f.value) for f in item.facts
}
+
+
+def test_a_gated_unit_counts_once_in_inventory_and_gated() -> None:
+ groups = [(None, "now", 2), ("test", None, 4)]
+ plain = queue_counts(groups, shown=2)
+ held = queue_counts(groups, shown=2, gated=3)
+ assert plain.gated == 0
+ assert held.inventory == plain.inventory + 3 and held.gated == 3
+ # No level below the inventory sees a gated unit.
+ assert (held.in_scope, held.eligible, held.due, held.excluded) == (
+ plain.in_scope,
+ plain.eligible,
+ plain.due,
+ plain.excluded,
+ )
diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.py
index f5aaca5cb..9ddba2e86 100644
--- a/tests/unit/server/mcp/test_health.py
+++ b/tests/unit/server/mcp/test_health.py
@@ -1655,7 +1655,7 @@ async def test_fix_first_named_page_honours_limit_and_cursor(setup_mcp, health_d
assert len(block["items"]) == min(eligible, FIX_FIRST_PAGE_CAP)
assert block["items_total"] == eligible
counts = block["counts"]
- assert set(counts) == {"inventory", "in_scope", "eligible", "due", "shown", "excluded"}
+ assert set(counts) == {"inventory", "in_scope", "eligible", "due", "shown", "excluded", "gated"}
assert counts["inventory"] >= counts["in_scope"] >= counts["eligible"] >= counts["due"]
assert counts["shown"] == len(block["items"])
assert all(n > 0 for n in counts["excluded"].values())
@@ -1793,6 +1793,7 @@ def test_fix_first_counts_split_scope_from_worth():
"due": 0,
"shown": 1,
"excluded": {"test": 4, "tooling": 1, "below_min_worth": 3},
+ "gated": 0,
}
diff --git a/tests/unit/server/test_language_gates_rest.py b/tests/unit/server/test_language_gates_rest.py
index b175fd300..5f2687dac 100644
--- a/tests/unit/server/test_language_gates_rest.py
+++ b/tests/unit/server/test_language_gates_rest.py
@@ -146,6 +146,25 @@ async def test_health_findings_and_overview(client: AsyncClient, app) -> None:
assert drawer["findings"] == [] and drawer["gated"]["java"]["count"] == 2
+async def test_queue_counts_take_a_gated_unit_once(client: AsyncClient, app) -> None:
+ repo_id = await _seed(client, app)
+ url = f"/api/repos/{repo_id}/health/overview"
+
+ def served(counts: dict) -> int:
+ return counts["eligible"] + sum(counts["excluded"].values())
+
+ held = (await _get(client, url))["queue_counts"]
+ opted = (await _get(client, url, include_unverified=True))["queue_counts"]
+ for unit in ("findings", "causes", "plans"):
+ counts, every = held[unit], opted[unit]
+ # The Java row is in the inventory once, as gated, and in no other level.
+ assert counts["gated"] == 1, unit
+ assert counts["inventory"] == served(counts) + counts["gated"], unit
+ # Opted in, nothing is held back and the inventory is the same rows.
+ assert every["gated"] == 0, unit
+ assert every["inventory"] == served(every) == counts["inventory"], unit
+
+
async def test_dead_code_list_and_summary(client: AsyncClient, app) -> None:
repo_id = await _seed(client, app)
base = f"/api/repos/{repo_id}/dead-code"
diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.py
index b6a1bf25f..6f1b347e2 100644
--- a/tests/unit/server/test_refactoring_opportunities.py
+++ b/tests/unit/server/test_refactoring_opportunities.py
@@ -350,6 +350,7 @@ async def test_every_surface_reports_the_same_counts(client, app):
"due": page["counts"]["due"],
"shown": 2,
"excluded": {"below_min_worth": 1, "test": 1},
+ "gated": 0,
}
overview = (await client.get(f"/api/repos/{repo_id}/health/overview")).json()
by_unit = overview["queue_counts"]