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.

refactor(health): serve the refactoring queue through the shared queue rules (#3291)

Raghav Chamadiyac3591a7ffbd4
diff --git a/packages/core/src/repowise/core/analysis/health/perf/serving.py b/packages/core/src/repowise/core/analysis/health/perf/serving.py
index bb842ebcb..69dad7088 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/serving.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/serving.py
@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING, Any, Literal
from repowise.core.analysis.health import queue_rules
from repowise.core.analysis.health.finding_identity import finding_public_id
from repowise.core.analysis.health.fix_first.text import perf_cost
-from repowise.core.analysis.health.queue_rules import NULL_VALUE, FilterRule, SortKeys
+from repowise.core.analysis.health.queue_rules import NULL_VALUE, Facet, FilterRule, SortKeys
from repowise.core.analysis.health.rows import detail_map, field, json_field
from repowise.core.analysis.health.worth import LOW_PRIORITY_LABEL, perf_low_priority
@@ -114,7 +114,7 @@ FILTERS: tuple[FilterRule, ...] = (
#: Facet name, the field it counts, and the filter parameter it is
#: cross-filtered by (``None``: no filter narrows it).
-FACETS: tuple[tuple[str, str, str | None], ...] = (
+FACETS: tuple[Facet, ...] = (
("context", "execution_context", "contexts"),
("boundary", "boundary_kind", "boundary"),
("confidence", "evidence_confidence", "confidence"),
@@ -123,9 +123,6 @@ FACETS: tuple[tuple[str, str, str | None], ...] = (
)
FACET_FIELDS = tuple(column for _, column, _ in FACETS)
-# The rules a facet group can be tested by: the ones on a facet's own field.
-_FACET_FILTERS = tuple(rule for rule in FILTERS if rule.field in FACET_FIELDS)
-
def sort_keys(sort: str | None) -> SortKeys:
"""The keys for *sort*; an unknown sort reads as rank."""
@@ -155,35 +152,21 @@ def _facet_selection(query: PerformanceQuery) -> dict[str, Any]:
}
-def _count(groups: list[dict[str, Any]], column: str, params: dict[str, Any]) -> dict[str, int]:
- counts: dict[str, int] = {}
- for group in groups:
- if queue_rules.keep(_FACET_FILTERS, group, params):
- key = group[column] or NULL_VALUE
- counts[key] = counts.get(key, 0) + group["count"]
- return counts
-
-
def fold_facets(
groups: Iterable[Sequence[Any]], query: PerformanceQuery
) -> dict[str, list[dict[str, Any]]]:
- """Fold ``(*facet fields, count)`` groups into per-value counts.
-
- Each facet is cross-filtered by the *other* selections: counting a facet
- under its own filter would leave every alternative at zero, so choosing
- one value would erase the others from the control.
- """
- rows = [dict(zip((*FACET_FIELDS, "count"), group, strict=True)) for group in groups]
- selection = _facet_selection(query)
- facets: dict[str, list[dict[str, Any]]] = {}
- for name, column, own in FACETS:
- others = {param: value for param, value in selection.items() if param != own}
- counts = _count(rows, column, others)
- facets[name] = [
+ """Fold ``(*facet fields, count)`` groups into per-value counts, largest
+ first, each facet cross-filtered by the query's other selections."""
+ folded = queue_rules.fold_facets(
+ groups, FACETS, rules=FILTERS, selection=_facet_selection(query), null=NULL_VALUE
+ )
+ return {
+ name: [
{"value": value, "total": total}
for value, total in sorted(counts.items(), key=lambda item: (-item[1], item[0]))
]
- return facets
+ for name, counts in folded.items()
+ }
def facet_counts(rows: Iterable[Any], query: PerformanceQuery) -> dict[str, list[dict[str, Any]]]:
diff --git a/packages/core/src/repowise/core/analysis/health/queue_rules.py b/packages/core/src/repowise/core/analysis/health/queue_rules.py
index 5b3cb427e..2971105d9 100644
--- a/packages/core/src/repowise/core/analysis/health/queue_rules.py
+++ b/packages/core/src/repowise/core/analysis/health/queue_rules.py
@@ -1,4 +1,4 @@
-"""Queue filter and sort rules as data, read over rows in memory.
+"""Queue filter, sort and facet rules as data, read over rows in memory.
A materialized queue (refactoring, performance) declares its filters as
:class:`FilterRule` rows and its orders as ``(field, descending)`` keys. The
@@ -13,7 +13,7 @@ through ``rows.field``.
from __future__ import annotations
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from typing import Any, Literal
@@ -26,6 +26,10 @@ NULL_VALUE = "none"
SortKeys = tuple[tuple[str, bool], ...]
+#: A facet: its name, the field it counts, and the filter parameter that
+#: narrows that field (``None``: none does).
+Facet = tuple[str, str, str | None]
+
@dataclass(frozen=True, slots=True)
class FilterRule:
@@ -90,12 +94,47 @@ def sort_key(keys: SortKeys, row: Any) -> tuple[Any, ...]:
return tuple(-field(row, name) if descending else field(row, name) for name, descending in keys)
+def fold_facets(
+ groups: Iterable[Sequence[Any]],
+ facets: Sequence[Facet],
+ *,
+ rules: Iterable[FilterRule] = (),
+ selection: Mapping[str, Any] | None = None,
+ null: str | None = None,
+) -> dict[str, dict[str, int]]:
+ """Fold ``(*facet fields, count)`` groups into ``{facet: {value: count}}``.
+
+ With a *selection*, each facet is cross-filtered by the *other* selections
+ under *rules*: counting a facet under its own filter would leave every
+ alternative at zero, so choosing one value would erase the others from the
+ control. A NULL (or, with *null* set, any empty) value counts as *null*;
+ without *null* it is skipped. A string *null* relabels any falsy value
+ (``""`` and ``0`` too); ``None`` skips NULLs only.
+ """
+ fields = tuple(column for _, column, _ in facets)
+ rows = [dict(zip((*fields, "count"), group, strict=True)) for group in groups]
+ facet_rules = tuple(rule for rule in rules if rule.field in fields)
+ folded: dict[str, dict[str, int]] = {}
+ for name, column, own in facets:
+ others = {param: value for param, value in (selection or {}).items() if param != own}
+ counts: dict[str, int] = {}
+ for row in rows:
+ value = row[column] if null is None else (row[column] or null)
+ if value is None or not keep(facet_rules, row, others):
+ continue
+ counts[str(value)] = counts.get(str(value), 0) + int(row["count"])
+ folded[name] = counts
+ return folded
+
+
__all__ = [
"NULL_VALUE",
+ "Facet",
"FilterOp",
"FilterRule",
"SortKeys",
"active_filters",
+ "fold_facets",
"keep",
"matches",
"sort_key",
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/serving.py b/packages/core/src/repowise/core/analysis/health/refactoring/serving.py
index e91209ce2..f45d2ada2 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/serving.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/serving.py
@@ -15,7 +15,8 @@ from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from typing import Any
-from repowise.core.analysis.health.queue_rules import FilterRule
+from repowise.core.analysis.health import queue_rules
+from repowise.core.analysis.health.queue_rules import Facet, FilterRule, SortKeys
from repowise.core.analysis.health.rows import detail_map, field
from .recommendations import _loads_dict
@@ -76,7 +77,7 @@ UNAVAILABLE: dict[str, Any] = {
#: Orders the queue can be read in, as ``(field, descending)`` keys. Every one
#: ends in a unique column so the total order is deterministic and a deep
#: offset cannot repeat or skip a row. A descending field must be numeric.
-SORTS: dict[str, tuple[tuple[str, bool], ...]] = {
+SORTS: dict[str, SortKeys] = {
"queue": (("queue_position", False),),
"rank": (("rank_position", False),),
"health": (("recoverable_health", True), ("rank_position", False)),
@@ -104,71 +105,34 @@ FILTERS: tuple[FilterRule, ...] = (
FilterRule("addresses_primary", "addresses_primary_problem", "is", "set"),
)
-#: Facet name -> the field it counts.
-FACETS: tuple[tuple[str, str], ...] = (
- ("lead_type", "lead_refactoring_type"),
- ("effort", "effort_bucket"),
- ("confidence", "confidence"),
+#: Facet name and the field it counts. No facet is cross-filtered: the counts
+#: are over the status and scope alone.
+FACETS: tuple[Facet, ...] = (
+ ("lead_type", "lead_refactoring_type", None),
+ ("effort", "effort_bucket", None),
+ ("confidence", "confidence", None),
)
+FACET_FIELDS = tuple(column for _, column, _ in FACETS)
-def active_filters(params: Any) -> list[tuple[FilterRule, Any]]:
- """The rules *params* (a query or a mapping) actually narrows by, with values."""
- active: list[tuple[FilterRule, Any]] = []
- for rule in FILTERS:
- value = field(params, rule.param)
- if rule.applies == "set" and value is None:
- continue
- if rule.applies == "truthy" and not value:
- continue
- active.append((rule, value))
- return active
-
-
-def _matches(rule: FilterRule, value: Any, actual: Any) -> bool:
- if rule.op == "eq":
- return actual == value
- if rule.op == "in":
- return actual in value
- if rule.op == "contains":
- # Ceiling: SQLite folds ASCII case only, Python folds Unicode; the two
- # differ only on a non-ASCII path fragment.
- return actual is not None and value.lower() in actual.lower()
- if rule.op == "prefix":
- # Case-sensitive, as PostgreSQL's LIKE is. SQLite's LIKE folds ASCII
- # case; paths differing only in case are not a case the queue meets.
- return actual is not None and actual.startswith(value)
- if rule.op == "positive":
- return (actual or 0) > 0
- # ``is``: SQL ``IS true/false``, so a NULL never matches either.
- return actual is not None and bool(actual) is bool(value)
+def sort_keys(order: str | None) -> SortKeys:
+ """The keys for *order*; an unknown order reads as the default."""
+ return SORTS.get(order or DEFAULT_ORDER, SORTS[DEFAULT_ORDER])
def keep(row: Any, params: Any) -> bool:
"""Whether *row* passes every filter *params* sets (a query or a mapping)."""
- return all(
- _matches(rule, value, field(row, rule.field)) for rule, value in active_filters(params)
- )
+ return queue_rules.keep(FILTERS, row, params)
def row_sort_key(row: Any, order: str | None = None) -> tuple[Any, ...]:
"""The sort key for *order*; an unknown order reads as the default."""
- key: list[Any] = []
- for name, descending in SORTS.get(order or DEFAULT_ORDER, SORTS[DEFAULT_ORDER]):
- value = field(row, name)
- key.append(-value if descending else value)
- return tuple(key)
+ return queue_rules.sort_key(sort_keys(order), row)
def fold_facets(groups: Iterable[Sequence[Any]]) -> dict[str, dict[str, int]]:
"""Fold ``(*facet values, count)`` groups into per-facet counts; a NULL is skipped."""
- facets: dict[str, dict[str, int]] = {name: {} for name, _ in FACETS}
- for group in groups:
- count = int(group[-1])
- for (name, _), key in zip(FACETS, group[:-1], strict=True):
- if key is not None:
- facets[name][str(key)] = facets[name].get(str(key), 0) + count
- return facets
+ return queue_rules.fold_facets(groups, FACETS)
def facet_counts(
@@ -177,7 +141,7 @@ def facet_counts(
"""Counts for every facet over the rows a status (and scope) selects."""
params = {"status": status, "opportunity_ids": opportunity_ids}
return fold_facets(
- (*(field(row, column) for _, column in FACETS), 1)
+ (*(field(row, column) for column in FACET_FIELDS), 1)
for row in rows
if keep(row, params)
)
@@ -551,12 +515,12 @@ __all__ = [
"DEFAULT_SCOPE",
"DEFAULT_VIEW",
"FACETS",
+ "FACET_FIELDS",
"FILTERS",
"SCOPES",
"SORTS",
"UNAVAILABLE",
"RefactoringQuery",
- "active_filters",
"directive_from_summary",
"evidence_block",
"facet_counts",
@@ -567,6 +531,7 @@ __all__ = [
"plan_payload",
"row_sort_key",
"serialize",
+ "sort_keys",
"stored_validation",
"summary_payload",
"validation_from_profile",
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py
index 9ce67e650..89de64775 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py
@@ -30,7 +30,7 @@ from ...models import (
_new_uuid,
_now_utc,
)
-from ...sql import LIKE_ESCAPE, escape_like
+from ...sql import order_by, rule_predicate
if TYPE_CHECKING:
from ....analysis.health.refactoring.opportunity import (
@@ -48,17 +48,6 @@ _LIVE_PLAN_STATUSES = frozenset({"open", "acknowledged"})
# and restate the decision as its own.
_DECIDED_STATUSES = frozenset({"resolved", "false_positive"})
-def _order_by(order: str | None) -> tuple[Any, ...]:
- """The ``ORDER BY`` for *order*, built from the serving layer's sort table."""
- from ....analysis.health.refactoring.serving import DEFAULT_ORDER, SORTS
-
- return tuple(
- getattr(RefactoringOpportunity, name).desc()
- if descending
- else getattr(RefactoringOpportunity, name).asc()
- for name, descending in SORTS.get(order or DEFAULT_ORDER, SORTS[DEFAULT_ORDER])
- )
-
# ---------------------------------------------------------------------------
# Writer
@@ -553,38 +542,23 @@ async def _write_summary(
# ---------------------------------------------------------------------------
-def _predicate(rule: Any, value: Any) -> Any:
- """One serving-layer filter rule as a SQL predicate."""
- column = getattr(RefactoringOpportunity, rule.field)
- if rule.op == "eq":
- return column == value
- if rule.op == "in":
- # One value is still one equality; an empty list matches nothing.
- return column == value[0] if len(value) == 1 else column.in_(value)
- if rule.op == "contains":
- # Escaping goes through the shared helper so a path fragment is read
- # as a path fragment here the same way it is everywhere else.
- return column.ilike(f"%{escape_like(value)}%", escape=LIKE_ESCAPE)
- if rule.op == "prefix":
- return column.like(f"{escape_like(value)}%", escape=LIKE_ESCAPE)
- if rule.op == "positive":
- return column > 0
- return column.is_(value)
-
-
def _opportunity_filters(repository_id: str, **params: Any) -> list[Any]:
"""The ``WHERE`` for *params*, built from the serving layer's filter table.
Only the current model's rows are served: an older model's ids are never
composed again, so a row of one is history, not queue.
"""
+ from ....analysis.health.queue_rules import active_filters
from ....analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION
- from ....analysis.health.refactoring.serving import active_filters
+ from ....analysis.health.refactoring.serving import FILTERS
return [
RefactoringOpportunity.repository_id == repository_id,
RefactoringOpportunity.refactoring_model_version == REFACTORING_MODEL_VERSION,
- *(_predicate(rule, value) for rule, value in active_filters(params)),
+ *(
+ rule_predicate(RefactoringOpportunity, rule, value)
+ for rule, value in active_filters(FILTERS, params)
+ ),
]
@@ -607,6 +581,8 @@ async def list_refactoring_opportunities(
offset: int = 0,
) -> tuple[list[RefactoringOpportunity], int]:
"""One page and its total: two statements, whatever the row count."""
+ from ....analysis.health.refactoring.serving import sort_keys
+
predicates = _opportunity_filters(
repository_id,
status=status,
@@ -630,7 +606,7 @@ async def list_refactoring_opportunities(
query: Select[Any] = (
select(RefactoringOpportunity)
.where(*predicates)
- .order_by(*_order_by(order))
+ .order_by(*order_by(RefactoringOpportunity, sort_keys(order)))
.offset(max(offset, 0))
.limit(max(limit, 0))
)
@@ -810,9 +786,9 @@ async def refactoring_facet_counts(
statement each, so adding a facet never adds a round trip.
``opportunity_ids`` narrows the counts to a scope the list applies too.
"""
- from ....analysis.health.refactoring.serving import FACETS, fold_facets
+ from ....analysis.health.refactoring.serving import FACET_FIELDS, fold_facets
- columns = tuple(getattr(RefactoringOpportunity, name) for _, name in FACETS)
+ columns = tuple(getattr(RefactoringOpportunity, name) for name in FACET_FIELDS)
rows = await session.execute(
select(*columns, func.count())
.where(
diff --git a/tests/unit/health/test_queue_rules.py b/tests/unit/health/test_queue_rules.py
new file mode 100644
index 000000000..0bec0e0cf
--- /dev/null
+++ b/tests/unit/health/test_queue_rules.py
@@ -0,0 +1,42 @@
+"""The shared facet fold both materialized queues count their controls with."""
+
+from __future__ import annotations
+
+from repowise.core.analysis.health.queue_rules import FilterRule, fold_facets
+from repowise.core.analysis.health.refactoring.serving import FACETS
+
+_FACETS = (("kind", "kind", "kinds"), ("size", "size", None))
+_RULES = (FilterRule("kinds", "kind", "in", "set"), FilterRule("size", "size", "eq", "set"))
+_GROUPS = [("a", "S", 2), ("a", None, 1), ("b", "S", 3), (None, "L", 4)]
+
+
+def test_plain_fold_skips_null_and_sums_counts() -> None:
+ assert fold_facets(_GROUPS, _FACETS) == {
+ "kind": {"a": 3, "b": 3},
+ "size": {"S": 5, "L": 4},
+ }
+
+
+def test_null_label_counts_an_empty_value() -> None:
+ folded = fold_facets(_GROUPS, _FACETS, null="none")
+ assert folded["kind"] == {"a": 3, "b": 3, "none": 4}
+ assert folded["size"] == {"S": 5, "none": 1, "L": 4}
+
+
+def test_each_facet_is_cross_filtered_by_the_other_selections_only() -> None:
+ folded = fold_facets(
+ _GROUPS, _FACETS, rules=_RULES, selection={"kinds": frozenset({"a"})}, null="none"
+ )
+ # The kind control ignores its own selection, so "b" stays choosable.
+ assert folded["kind"] == {"a": 3, "b": 3, "none": 4}
+ # The size control is narrowed by the kind selection.
+ assert folded["size"] == {"S": 2, "none": 1}
+
+
+def test_without_null_label_an_empty_string_is_its_own_key() -> None:
+ folded = fold_facets([("", "S", "high", 1)], FACETS)
+ assert folded["lead_type"] == {"": 1}
+
+
+def test_no_groups_still_returns_every_facet() -> None:
+ assert fold_facets([], FACETS) == {name: {} for name, _, _ in FACETS}