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): hold findings on vendored and generated files and history markers on tests at serving (#3840)

Raghav Chamadiya39b62b3953bc
diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.md
index 3ef4ec740..b032f3e89 100644
--- a/docs/layers/REFACTORING.md
+++ b/docs/layers/REFACTORING.md
@@ -142,6 +142,10 @@ usual but held back pending verification: the plan lists, the queue, its facets
and the rollup's lead leave them out unless the caller passes
`include_unverified`, and responses count them in `gated`.
+Plans and opportunities on test files are held back the same way on every plan
+surface, `scope=all` included, as Fix first already leaves them out. They are
+counted in `gated` under `test`.
+
Break Cycle is advisory. Its plan names edges to cut, not which symbols cross
them or how to move them, so an opportunity carries it as `evidence` instead of
as a numbered step: it never leads, and never reaches Fix first. The plan itself
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index b39dbabf8..d9169b466 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -385,6 +385,10 @@ Provisional finding types appear only with `include=["unverified"]`, each marked
Health findings, refactoring plans and opportunities, and performance opportunities on Java, C#, C and C++ files are held back pending verification for those languages. They are still stored and a lookup by id still answers; `_meta.gated` counts them per layer and language, and `include=["unverified"]` shows them.
+Health findings on files the index stores as vendored or generated are held back the same way, in every language: that code is changed upstream or by its generator. `_meta.gated.health` counts them under `vendored` and `generated` as plain numbers, and `_meta.gated.reasons` gives each reason once when the call lists no finding. Scores, KPIs and the worst-file order still count them.
+
+On test files, history markers (ownership, churn, change entropy, co-change and the other git-derived kinds) are held back too, counted under `test_history`: they describe how a test changes, not a defect in it. Code-shape findings on tests are still listed.
+
### Opt-in blocks
| `include` | Adds |
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/persist.py b/packages/cli/src/repowise/cli/commands/health_cmd/persist.py
index 0a05c43e4..e2c68db79 100644
--- a/packages/cli/src/repowise/cli/commands/health_cmd/persist.py
+++ b/packages/cli/src/repowise/cli/commands/health_cmd/persist.py
@@ -131,7 +131,8 @@ def _load_stored_report(repo_path: object) -> tuple[Any, set[str], dict[str, str
metrics = await get_health_metrics(session, repo_id)
if not metrics:
return None
- findings = await get_health_findings(session, repo_id)
+ # KPIs count what the scores counted, file-held findings included.
+ findings = await get_health_findings(session, repo_id, file_holds=False)
hotspots = await get_hotspot_file_paths(session, repo_id)
languages = await get_file_language_map(session, repo_id)
kpis = compute_kpis(metrics, hotspots, deductions=deduction_by_path(findings))
diff --git a/packages/core/src/repowise/core/analysis/change_health/models.py b/packages/core/src/repowise/core/analysis/change_health/models.py
index 19a816424..e886cd812 100644
--- a/packages/core/src/repowise/core/analysis/change_health/models.py
+++ b/packages/core/src/repowise/core/analysis/change_health/models.py
@@ -60,6 +60,7 @@ SkipReason = Literal[
"not_analyzable_data",
"unsupported_language",
"generated",
+ "vendored",
"binary",
"excluded",
"deleted",
diff --git a/packages/core/src/repowise/core/analysis/change_health/service.py b/packages/core/src/repowise/core/analysis/change_health/service.py
index eb5bf0c2d..46c77b185 100644
--- a/packages/core/src/repowise/core/analysis/change_health/service.py
+++ b/packages/core/src/repowise/core/analysis/change_health/service.py
@@ -268,6 +268,7 @@ class ChangeHealthDeltaService:
)
skipped.update(head_run.skipped)
+ skipped.update(_held_origins(head_sources, self.repo_path))
# A file whose BASE side failed has no baseline, so every finding at its
# head would read as introduced. Drop it from the subject and say so:
# silently keeping it is how a partial run fabricates new findings.
@@ -409,6 +410,22 @@ def _nothing_compared(changes: list[FileChange], skipped: dict[str, str]) -> str
return "No changed file is health-analyzable, so nothing was compared."
+def _held_origins(sources: dict[str, bytes], repo_root: str | None) -> dict[str, str]:
+ """``{path: "vendored" | "generated"}`` for the changed files every health
+ surface holds back by origin. Read from the head bytes with the classifier
+ the index stores ``code_origin`` from, so a file the index has not seen yet
+ (new in this change) is classed the same way it will be once indexed."""
+ from ...code_origin import code_origin
+ from ..finding_registry import HELD_ORIGINS
+
+ out: dict[str, str] = {}
+ for path, raw in sources.items():
+ origin = code_origin(path, raw, repo_root=repo_root)
+ if origin in HELD_ORIGINS:
+ out[path] = origin
+ return out
+
+
def _skip_reason(change: FileChange) -> str:
"""Why a changed path never reached the analyzer."""
if change.head_path is None:
diff --git a/packages/core/src/repowise/core/analysis/finding_registry.py b/packages/core/src/repowise/core/analysis/finding_registry.py
index 1e791c007..85df74321 100644
--- a/packages/core/src/repowise/core/analysis/finding_registry.py
+++ b/packages/core/src/repowise/core/analysis/finding_registry.py
@@ -171,6 +171,46 @@ LANGUAGE_GATES: tuple[LanguageGate, ...] = (
)
+#: Why a health finding is held back by the file it sits on rather than by its
+#: language: vendored and generated code is not the reader's to change, and a
+#: history marker on a test file describes how the test changes, not a defect
+#: in it. A refactoring plan or opportunity on a test file is held back too:
+#: Fix first never offers one, and no other plan surface does either. Read from
+#: the file's stored ``code_origin`` and ``is_test``, so it holds on every
+#: language, with the same opt-in as a language gate.
+FILE_HOLDS: dict[str, str] = {
+ "vendored": "Held back on vendored files: the code is maintained upstream.",
+ "generated": "Held back on generated files: change what generates them instead.",
+ "test_history": "History markers held back on test files: they describe change, not a defect.",
+ "test": "Plans held back on test files: tests change with the code they cover.",
+}
+
+#: The stored ``code_origin`` values a health finding is never served on.
+HELD_ORIGINS: tuple[str, ...] = ("vendored", "generated")
+
+
+def history_kinds() -> frozenset[str]:
+ """The health markers read from git history alone (the ``test_history`` hold)."""
+ # Deferred: the health package imports this module.
+ from repowise.core.analysis.health.scoring import history_biomarkers
+
+ return history_biomarkers()
+
+
+def file_hold(layer: GateLayer, kind: Any, code_origin: Any, is_test: Any) -> str | None:
+ """The :data:`FILE_HOLDS` key holding back a *layer* row of *kind* on a file
+ with that stored origin and test flag, or ``None``."""
+ if layer == "refactoring":
+ return "test" if is_test is True else None
+ if layer != "health":
+ return None
+ if code_origin in HELD_ORIGINS:
+ return str(code_origin)
+ if is_test is True and kind in history_kinds():
+ return "test_history"
+ return None
+
+
def gates_on(layer: GateLayer) -> tuple[LanguageGate, ...]:
"""The gates on *layer*, read from :data:`LANGUAGE_GATES` at call time."""
return tuple(gate for gate in LANGUAGE_GATES if gate.layer == layer)
@@ -223,15 +263,59 @@ def held_back_note(languages: Iterable[str]) -> str:
def gated_summary(layer: GateLayer, counts: Mapping[str, int]) -> dict[str, dict]:
"""``{language: {count, reason}}`` for each gated language with rows on
*layer*, so a surface says what it held back. The reason says only that
- the layer is held back pending verification there."""
+ the layer is held back pending verification there. A :data:`FILE_HOLDS`
+ key in *counts* is reported under that key with its reason."""
out: dict[str, dict] = {}
for gate in gates_on(layer):
count = counts.get(gate.language, 0)
if count:
out[gate.language] = {"count": count, "reason": held_back_note([gate.language])}
+ # File holds ride beside the languages under their own keys, with their reason.
+ for key, reason in FILE_HOLDS.items():
+ if counts.get(key):
+ out[key] = {"count": counts[key], "reason": reason}
return out
+def row_hold(
+ layer: GateLayer,
+ row: Any,
+ files: Mapping[str, Any] | None,
+ *,
+ kind: str,
+ get: Callable[[Any, str], Any] = getattr,
+) -> str | None:
+ """The :data:`FILE_HOLDS` key on *row*, read off its file's metric row in
+ *files* (``code_origin``, ``is_test``); a path missing from it is not held."""
+ metric = (files or {}).get(get(row, "file_path") or "")
+ if metric is None:
+ return None
+ return file_hold(
+ layer, get(row, kind), getattr(metric, "code_origin", None), getattr(metric, "is_test", None)
+ )
+
+
+def split_held(
+ layer: GateLayer,
+ rows: Iterable[Any],
+ files: Mapping[str, Any] | None,
+ *,
+ kind: str,
+ get: Callable[[Any, str], Any] = getattr,
+) -> tuple[list[Any], dict[str, int]]:
+ """``(rows no file hold keeps back, {hold key: count})`` for rows already in
+ memory whose language gates were applied when they were read."""
+ kept: list[Any] = []
+ counts: dict[str, int] = {}
+ for row in rows:
+ key = row_hold(layer, row, files, kind=kind, get=get)
+ if key is None:
+ kept.append(row)
+ else:
+ counts[key] = counts.get(key, 0) + 1
+ return kept, counts
+
+
def split_gated(
layer: GateLayer,
rows: Iterable[Any],
@@ -239,22 +323,27 @@ def split_gated(
kind: str,
get: Callable[[Any, str], Any] = getattr,
include_unverified: bool = False,
+ files: Mapping[str, Any] | None = None,
) -> tuple[list[Any], dict[str, dict]]:
"""``(rows no gate holds back, gated_summary)`` for rows already in memory.
*kind* names the row field holding the finding type; *get* reads a field.
- ``include_unverified`` keeps every row and reports nothing held back.
+ *files* maps a path to its health metric row so the :data:`FILE_HOLDS`
+ apply too (:func:`row_hold`). ``include_unverified`` keeps every row and
+ reports nothing held back.
"""
if include_unverified:
return list(rows), {}
shown: list[Any] = []
counts: dict[str, int] = {}
for row in rows:
- gate = gate_for(layer, get(row, "file_path") or "", get(row, kind))
- if gate is None:
+ held = row_hold(layer, row, files, kind=kind, get=get)
+ gate = None if held else gate_for(layer, get(row, "file_path") or "", get(row, kind))
+ key = held or (gate.language if gate is not None else None)
+ if key is None:
shown.append(row)
else:
- counts[gate.language] = counts.get(gate.language, 0) + 1
+ counts[key] = counts.get(key, 0) + 1
return shown, gated_summary(layer, counts)
@@ -302,6 +391,8 @@ def withheld_summary(counts: Mapping[str, int], excluded: Iterable[str]) -> dict
__all__ = [
+ "FILE_HOLDS",
+ "HELD_ORIGINS",
"LANGUAGE_GATES",
"REGISTRY",
"UNVERIFIED_LABEL",
@@ -310,14 +401,18 @@ __all__ = [
"GateLayer",
"LanguageGate",
"excluded_types",
+ "file_hold",
"gate_for",
"gated_extensions",
"gated_summary",
"gates_on",
+ "history_kinds",
"is_served",
"is_shown",
"language_of",
+ "row_hold",
"split_gated",
+ "split_held",
"status_of",
"verification_label",
"withheld_summary",
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/class_analysis.py b/packages/core/src/repowise/core/analysis/health/complexity/class_analysis.py
index 1f9d15b77..62bb558e7 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/class_analysis.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/class_analysis.py
@@ -680,10 +680,10 @@ def _collect_classes(
# A partial class's other parts live in files this pass does not see;
# a trait impl's methods are the trait's, so none can move out.
contract_impl = is_trait_impl(class_node, lmap)
+ refs = _class_member_refs(body, method_fcs, lmap, _class_name(class_node))
if "partial" in _decl_words(class_node) or contract_impl:
lcom4, field_count, components, tcc = 1, 0, [], 1.0
else:
- refs = _class_member_refs(body, method_fcs, lmap, _class_name(class_node))
lcom4, field_count, components, tcc = _compute_lcom4(
body.methods, method_fcs, lmap, refs
)
@@ -701,6 +701,18 @@ def _collect_classes(
components=components,
tcc=tcc,
contract_impl=contract_impl,
+ # A partial fragment's own fields still bind the methods that use them.
+ field_readers=_field_readers(method_fcs, refs),
)
)
return classes
+
+
+def _field_readers(method_fcs: list[FunctionComplexity], refs: _MemberRefs) -> frozenset[str]:
+ """Names of the methods whose references include a field, not a method."""
+ methods = {fc.name for fc in method_fcs} | refs.call_targets
+ return frozenset(
+ fc.name
+ for fc, members in zip(method_fcs, refs.per_method, strict=True)
+ if members - methods
+ )
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/models.py b/packages/core/src/repowise/core/analysis/health/complexity/models.py
index 42654d71f..42b4d8717 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/models.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/models.py
@@ -225,6 +225,11 @@ class ClassComplexity:
# Every method is fixed by a contract the class implements (a Rust
# ``impl Trait for T``): none can move out, and cohesion is not scored.
contract_impl: bool = False
+ # Names of the methods that read or write an instance field of this class,
+ # explicitly or by bare name. ``components`` drops single-field groups on
+ # implicit-receiver languages, so a service method using its one injected
+ # repository is only visible here; Move Method reads it.
+ field_readers: frozenset[str] = frozenset()
@dataclass(frozen=True)
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/move_method.py b/packages/core/src/repowise/core/analysis/health/refactoring/move_method.py
index 1022cc94a..eedb6119f 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/move_method.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/move_method.py
@@ -42,8 +42,9 @@ module-level helpers plus ``result.record`` / ``result.note`` on a collector it
was handed looked like it envied the collector.
The ``calls`` graph does not see field reads, so own-class use is also read
-off the class's cohesion components: a method that shares a component holding
-fields works on its own class's state and stays. A method that fulfils a
+off the class analysis: a method that reads one of its class's fields (a
+service method using the repository injected into its constructor) or shares
+a component holding fields works on its own class's state and stays. A method that fulfils a
contract (``@Override``, an ``override`` / ``virtual`` / ``abstract``
modifier, a member its base class or interface declares, a runtime contract
name such as ``toString``) cannot move either, since the type it overrides for
@@ -279,10 +280,18 @@ def _uses_own_state(classes: list[Any], parent: str, name: str, line: int | None
def _binds_method(cls: Any, name: str) -> bool:
- """Whether *cls* holds method *name* in place: a contract impl, or a
- cohesion component with fields or outside calls that contains it."""
+ """Whether *cls* holds method *name* in place: a contract impl, a method
+ that uses an instance field of the class (an injected repository or
+ client, read by bare name in Java), or a cohesion component with fields or
+ outside calls that contains it."""
if getattr(cls, "contract_impl", False):
return True
+ # ``getattr``: a walk cached before the field existed reads as no signal.
+ # Ceiling: only languages with class analysis fill it (Go emits no classes,
+ # so a Go receiver's fields are not read here); static fields such as a
+ # ``static final`` logger never count, being no instance's state.
+ if name in getattr(cls, "field_readers", ()):
+ return True
groups = getattr(cls, "components", None) or ()
return any(name in g.methods and (g.fields or g.calls) for g in groups)
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
index b8f43f470..a1be55994 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
@@ -75,6 +75,7 @@ from .health import (
backfill_is_test,
backfill_module_attribution,
clear_unanalysed_scores,
+ gated_health_counts,
get_deduction_by_path,
get_file_language_map,
get_headline_health,
@@ -157,6 +158,7 @@ __all__ = [
"finalize_refactoring_opportunities",
"finalize_refactoring_suggestions",
"finding_data_from_row",
+ "gated_health_counts",
"gated_performance_counts",
"get_coverage_summary",
"get_dead_code_findings",
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health.py b/packages/core/src/repowise/core/persistence/crud/analysis/health.py
index db1a498a9..8328c9d44 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health.py
@@ -50,7 +50,7 @@ from ...models import (
from .._shared import _BATCH_SIZE
from ..graph import get_test_file_paths
from .plain_rows import plain_rows
-from .shown import shown
+from .shown import gated_counts, shown
def _health_finding_row_kwargs(finding: Any, repository_id: str) -> dict:
@@ -497,6 +497,7 @@ async def get_health_findings(
status: str = "open",
include_withheld: bool = False,
include_unverified: bool = False,
+ file_holds: bool = True,
limit: int | None = None,
) -> list[HealthFinding]:
"""Findings for one repository: production ahead of test files, worth doing
@@ -509,7 +510,9 @@ async def get_health_findings(
returned. Files of a language the registry gates for health findings are
left out too, unless ``include_unverified`` (which also opts into every
provisional type). ``include_withheld`` is for analysis that must see every
- row.
+ row. ``file_holds=False`` keeps the findings held back by their file
+ (vendored, generated, history on a test) for a reader that sums scores or
+ KPIs, which count them.
``exclude_dimensions`` is how a general queue keeps a dimension out of a
ranking it does not share units with. It is ignored when ``dimension``
@@ -551,6 +554,7 @@ async def get_health_findings(
HealthFinding.file_path,
requested=types,
include_unverified=include_unverified,
+ file_holds=file_holds,
)
)
if file_path is not None:
@@ -600,6 +604,33 @@ async def get_health_findings(
return ordered if limit is None else ordered[:limit]
+async def gated_health_counts(
+ session: AsyncSession,
+ repository_id: str,
+ *,
+ file_path: str | None = None,
+ include_unverified: bool = False,
+) -> dict[str, dict]:
+ """``{language or file hold: {count, reason}}`` over the open findings
+ :func:`get_health_findings` leaves out by default, so a list says why it
+ is shorter than the stored scores suggest."""
+ where = [
+ HealthFinding.repository_id == repository_id,
+ HealthFinding.status == "open",
+ HealthFinding.biomarker_type.not_in(excluded_types()),
+ ]
+ if file_path is not None:
+ where.append(HealthFinding.file_path == file_path)
+ return await gated_counts(
+ session,
+ "health",
+ HealthFinding,
+ *where,
+ kind_col=HealthFinding.biomarker_type,
+ include_unverified=include_unverified,
+ )
+
+
async def health_finding_priorities(
session: AsyncSession, repository_id: str, findings: Sequence[HealthFinding]
) -> dict[str, LowPriority | None]:
@@ -777,7 +808,10 @@ async def _open_finding_totals_rows(session: AsyncSession, repository_id: str) -
.where(
HealthFinding.repository_id == repository_id,
HealthFinding.status == "open",
- shown("health", HealthFinding.biomarker_type, HealthFinding.file_path),
+ # The totals sum what the scores counted, file-held rows included.
+ shown(
+ "health", HealthFinding.biomarker_type, HealthFinding.file_path, file_holds=False
+ ),
)
.order_by(HealthFinding.health_impact.desc(), HealthFinding.id)
)
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py
index 2f406bdad..ea9b9692b 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py
@@ -474,13 +474,14 @@ def _registry_shown_plan() -> Any:
)
-def shown_plan_predicate(*, include_unverified: bool = False) -> Any:
+def shown_plan_predicate(*, include_unverified: bool = False, file_holds: bool = True) -> Any:
"""Plans whose source biomarker the finding registry does not withhold, on
files of a language no gate holds refactoring back on.
Plans are persisted whatever the registry says; every surface that lists
them filters here. A plan with no source biomarker (structural) is shown.
- ``include_unverified`` opts into the gated languages.
+ ``include_unverified`` opts into the gated languages and the plans on test
+ files; ``file_holds=False`` keeps the test-file plans without that opt-in.
"""
return and_(
_registry_shown_plan(),
@@ -489,6 +490,7 @@ def shown_plan_predicate(*, include_unverified: bool = False) -> Any:
RefactoringSuggestion.file_path,
RefactoringSuggestion.refactoring_type,
include_unverified=include_unverified,
+ file_holds=file_holds,
),
)
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 8b83a706e..248a56361 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
@@ -301,7 +301,9 @@ async def _rank_live_plans(
select(RefactoringSuggestion).where(
RefactoringSuggestion.repository_id == repository_id,
RefactoringSuggestion.status.in_(tuple(_LIVE_PLAN_STATUSES)),
- shown_plan_predicate(),
+ # Test-file plans still rank: the hold is a serving rule, and
+ # ranking without them would move the tests the others list.
+ shown_plan_predicate(file_holds=False),
)
)
).scalars()
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/shown.py b/packages/core/src/repowise/core/persistence/crud/analysis/shown.py
index b177aa623..39b246135 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/shown.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/shown.py
@@ -1,7 +1,9 @@
"""The finding registry as SQL: what a serving read may show.
-``finding_registry`` decides by finding type (``excluded_types``) and by layer
-and language (``LANGUAGE_GATES``). Reads that list or count rows for a surface
+``finding_registry`` decides by finding type (``excluded_types``), by layer
+and language (``LANGUAGE_GATES``), and for health findings by the file's stored
+origin and test flag (``FILE_HOLDS``), which also hold refactoring plans
+back on test files. Reads that list or count rows for a surface
filter here, so every surface agrees on what is held back. Reads by id and the
writers do not: a held-back row is still stored and addressable.
"""
@@ -15,17 +17,69 @@ from sqlalchemy import and_, case, func, not_, or_, select, true
from sqlalchemy.ext.asyncio import AsyncSession
from ....analysis.finding_registry import (
+ HELD_ORIGINS,
GateLayer,
excluded_types,
gated_extensions,
gated_summary,
gates_on,
+ history_kinds,
)
+from ...models import (
+ HealthFileMetric,
+ HealthFinding,
+ RefactoringOpportunity,
+ RefactoringSuggestion,
+)
+
+# The row types each layer's file holds read, and only these: a hold is a join
+# on the row's repository and path.
+_HELD_MODELS: dict[str, tuple[Any, ...]] = {
+ "health": (HealthFinding,),
+ "refactoring": (RefactoringSuggestion, RefactoringOpportunity),
+}
+
+
+def _file_holds(layer: GateLayer, path_col: Any, kind_col: Any) -> list[tuple[str, Any]]:
+ """``(FILE_HOLDS key, row matches it)`` for health findings and plans, read
+ from the file's stored metric row; ahead of the language cells, as
+ ``file_hold`` is."""
+ model = getattr(path_col, "class_", None)
+ if model not in _HELD_MODELS.get(layer, ()):
+ return []
+
+ def on_file(*where: Any) -> Any:
+ return (
+ select(HealthFileMetric.id)
+ .where(
+ HealthFileMetric.repository_id == model.repository_id,
+ HealthFileMetric.file_path == path_col,
+ *where,
+ )
+ .exists()
+ )
+
+ if layer == "refactoring":
+ return [("test", on_file(HealthFileMetric.is_test.is_(True)))]
+ cells = [(origin, on_file(HealthFileMetric.code_origin == origin)) for origin in HELD_ORIGINS]
+ if kind_col is not None:
+ cells.append(
+ (
+ "test_history",
+ and_(
+ kind_col.in_(sorted(history_kinds())),
+ on_file(HealthFileMetric.is_test.is_(True)),
+ ),
+ )
+ )
+ return cells
-def _cells(layer: GateLayer, path_col: Any, kind_col: Any) -> list[tuple[str, Any]]:
- """``(language, row matches that gate)`` for each gate on *layer*."""
- cells = []
+def _cells(
+ layer: GateLayer, path_col: Any, kind_col: Any, *, file_holds: bool = True
+) -> list[tuple[str, Any]]:
+ """``(key, row matches it)`` for each file hold, then each gate on *layer*."""
+ cells = _file_holds(layer, path_col, kind_col) if file_holds else []
for gate in gates_on(layer):
match = or_(*(path_col.ilike(f"%{ext}") for ext in gated_extensions(gate.language)))
if gate.kinds is not None:
@@ -35,10 +89,18 @@ def _cells(layer: GateLayer, path_col: Any, kind_col: Any) -> list[tuple[str, An
def ungated(
- layer: GateLayer, path_col: Any, kind_col: Any = None, *, include_unverified: bool = False
+ layer: GateLayer,
+ path_col: Any,
+ kind_col: Any = None,
+ *,
+ include_unverified: bool = False,
+ file_holds: bool = True,
) -> Any:
- """Rows of *layer* no language gate holds back (everything when opted in)."""
- cells = [] if include_unverified else _cells(layer, path_col, kind_col)
+ """Rows of *layer* no language gate or file hold keeps back (everything when
+ opted in). ``file_holds=False`` applies the language gates alone."""
+ cells = (
+ [] if include_unverified else _cells(layer, path_col, kind_col, file_holds=file_holds)
+ )
return not_(or_(*(match for _, match in cells))) if cells else true()
@@ -49,17 +111,25 @@ def shown(
*,
requested: Iterable[str] = (),
include_unverified: bool = False,
+ file_holds: bool = True,
) -> Any:
"""Rows whose type the registry shows and whose language no gate holds back.
*kind_col* holds a registry type (a biomarker type or a dead-code kind).
``include_unverified`` opts into provisional types and gated languages alike.
+ ``file_holds=False`` keeps the file-held rows: a score or KPI counts them.
"""
return and_(
kind_col.not_in(
excluded_types(requested=requested, include_provisional=include_unverified)
),
- ungated(layer, path_col, kind_col, include_unverified=include_unverified),
+ ungated(
+ layer,
+ path_col,
+ kind_col,
+ include_unverified=include_unverified,
+ file_holds=file_holds,
+ ),
)
@@ -73,7 +143,7 @@ async def gated_counts(
) -> dict[str, dict]:
"""What the gates on *layer* hold back among *model* rows matching *where*.
- ``{language: {count, reason}}``, from one grouped count, so a
+ ``{language or file hold: {count, reason}}``, from one grouped count, so a
surface can say how many rows it left out and why instead of reading empty.
Empty when ``include_unverified``: nothing was held back.
"""
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/findings.py b/packages/server/src/repowise/server/mcp_server/tool_health/findings.py
index 7f1c3816c..34e6f243f 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/findings.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/findings.py
@@ -7,6 +7,7 @@ from typing import Any
from sqlalchemy import select
+from repowise.core.analysis.finding_registry import split_held
from repowise.core.analysis.health.worth import LOW_PRIORITY_LABEL, finding_priorities
from repowise.core.persistence.crud.analysis.plain_rows import plain_rows
from repowise.core.persistence.crud.analysis.shown import gated_counts, ungated
@@ -80,6 +81,9 @@ def _tiered(rows: list[Any], measured_over: list[Any]) -> tuple[list[Any], dict[
def _open_findings(repository: Any, req: HealthRequest) -> tuple[Any, ...]:
+ """Open findings no language gate holds back. File holds are applied after
+ the read (:func:`_listed`): the leads, worst-file order and KPIs count the
+ file-held rows, as the scores did."""
return (
*_open_typed(repository, req),
ungated(
@@ -87,10 +91,18 @@ def _open_findings(repository: Any, req: HealthRequest) -> tuple[Any, ...]:
HealthFinding.file_path,
HealthFinding.biomarker_type,
include_unverified=req.include_unverified,
+ file_holds=False,
),
)
+def _listed(rows: list[Any], pop: Population, req: HealthRequest) -> list[Any]:
+ """*rows* a finding list may show: those no file hold keeps back."""
+ if req.include_unverified:
+ return rows
+ return split_held("health", rows, pop.files, kind="biomarker_type")[0]
+
+
def _open_typed(repository: Any, req: HealthRequest) -> tuple[Any, ...]:
"""Open findings of a type the registry shows, before any language gate."""
return (
@@ -137,7 +149,8 @@ async def load_targeted_findings(
"file_path",
))
emitted, labels = _tiered(
- [f for f in finding_rows if _in_dimensions(f, req.ranked_dimensions)], finding_rows
+ [f for f in _listed(finding_rows, pop, req) if _in_dimensions(f, req.ranked_dimensions)],
+ finding_rows,
)
return FindingSets(
finding_rows=emitted,
@@ -162,7 +175,9 @@ async def load_dashboard_findings(
)
# ``lead_rows`` stays unfiltered: the leads and performance KPI must not
# change because the caller asked to see one dimension.
- dimensioned = [r for r in lead_rows if _in_dimensions(r, req.ranked_dimensions)]
+ dimensioned = [
+ r for r in _listed(lead_rows, pop, req) if _in_dimensions(r, req.ranked_dimensions)
+ ]
ranked = req.ranks_findings
# Tiering measures every open finding; a call that only counts them skips it.
emitted, labels = _tiered(dimensioned, lead_rows) if ranked else (dimensioned, {})
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/population.py b/packages/server/src/repowise/server/mcp_server/tool_health/population.py
index cae1c5da7..8168721cc 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/population.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/population.py
@@ -2,7 +2,7 @@
from __future__ import annotations
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from typing import Any
from sqlalchemy import select
@@ -39,6 +39,9 @@ class Population:
matched_modules: set[str]
scoped: bool
effective_targets: list[str]
+ #: Every stored metric row by path, before any narrowing: the file holds
+ #: read a finding's file origin and test flag off it.
+ files: dict[str, Any] = field(default_factory=dict)
@property
def code_shape(self) -> bool:
@@ -129,4 +132,5 @@ async def load_population(
matched_modules=matched_modules,
scoped=scoped,
effective_targets=file_targets if scoped else [],
+ files={m.file_path: m for m in indexed_rows},
)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
index 0a969b20f..a2ddbcaa1 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
@@ -13,7 +13,7 @@ from collections import Counter
from time import perf_counter
from typing import Any
-from repowise.core.analysis.finding_registry import withheld_summary
+from repowise.core.analysis.finding_registry import FILE_HOLDS, withheld_summary
from repowise.core.analysis.health.counts import DEFAULT_COUNTS
from repowise.core.analysis.health.refactoring.serving import (
DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT,
@@ -282,10 +282,21 @@ async def get_health(
def _attach_gated(meta: dict[str, Any], data: HealthData) -> None:
- """What a language gate held back, in ``_meta`` so no ``only`` projection
- drops it: an agent must read "held back", never "nothing found"."""
- if data.gated:
- meta["gated"] = {**data.gated, "opt_in": {"include": ["unverified"]}}
+ """What a language gate or file hold held back, in ``_meta`` so no ``only``
+ projection drops it: an agent must read "held back", never "nothing found"."""
+ if not data.gated:
+ return
+ # A file hold is a count per key: its reason is one fixed sentence, sent
+ # once under ``reasons`` and only when the call lists no finding, so a
+ # default response grows by a few tokens at most.
+ gated: dict[str, Any] = {
+ layer: {k: v["count"] if k in FILE_HOLDS else v for k, v in cells.items()}
+ for layer, cells in data.gated.items()
+ }
+ held = sorted({k for cells in data.gated.values() for k in cells if k in FILE_HOLDS})
+ if held and not data.findings.emitted:
+ gated["reasons"] = {k: FILE_HOLDS[k] for k in held}
+ meta["gated"] = {**gated, "opt_in": {"include": ["unverified"]}}
def _attach_withheld(result: dict[str, Any], data: HealthData) -> None:
diff --git a/packages/server/src/repowise/server/routers/code_health/files_routes.py b/packages/server/src/repowise/server/routers/code_health/files_routes.py
index ae03b9bc6..150620ccc 100644
--- a/packages/server/src/repowise/server/routers/code_health/files_routes.py
+++ b/packages/server/src/repowise/server/routers/code_health/files_routes.py
@@ -7,7 +7,7 @@ from typing import Any
from fastapi import Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.finding_registry import split_gated
+from repowise.core.analysis.finding_registry import FILE_HOLDS, HELD_ORIGINS, split_gated
from repowise.core.analysis.health.perf.coverage import supported_perf_languages
from repowise.core.analysis.health.suggestions import suggestion_for as _suggestion_for
from repowise.core.analysis.health.trends import file_trend
@@ -130,18 +130,32 @@ async def list_health_files(
"offset": offset,
"limit": limit,
"files": [
- _metric_to_dict(
+ _held_row(
+ _metric_to_dict(
+ m,
+ leads.get(m.file_path),
+ perf_findings=perf_counts.get(m.file_path, 0),
+ perf_analyzed=lang_by_path.get(m.file_path) in perf_langs,
+ summary=summary,
+ ),
m,
- leads.get(m.file_path),
- perf_findings=perf_counts.get(m.file_path, 0),
- perf_analyzed=lang_by_path.get(m.file_path) in perf_langs,
- summary=summary,
)
for m in page
],
+ # What the finding reads above left out, by language or file hold.
+ "gated": await crud.gated_health_counts(session, repo_id),
}
+def _held_row(row: dict, metric: Any) -> dict:
+ """*row*, saying why its findings are not listed when its file's origin
+ holds every one of them back (its score still counts them)."""
+ origin = getattr(metric, "code_origin", None)
+ if origin in HELD_ORIGINS:
+ row["held_reason"] = FILE_HOLDS[origin]
+ return row
+
+
@router.get("/api/repos/{repo_id}/health/files/breakdown")
async def file_score_breakdown(
repo_id: str,
@@ -160,7 +174,11 @@ async def file_score_breakdown(
# The score counts every finding; a gated one is held back from the list
# and the breakdown, and ``gated`` says how many.
findings, gated = split_gated(
- "health", findings, kind="biomarker_type", include_unverified=include_unverified
+ "health",
+ findings,
+ kind="biomarker_type",
+ include_unverified=include_unverified,
+ files={m.file_path: m for m in metrics},
)
# This drawer opens from a row the reader just saw a score on. Reading it
# under the other counts would answer a click on 8.5 with a 2.0 and list
diff --git a/packages/server/src/repowise/server/routers/code_health/findings_routes.py b/packages/server/src/repowise/server/routers/code_health/findings_routes.py
index 531649ced..7be2e8b7a 100644
--- a/packages/server/src/repowise/server/routers/code_health/findings_routes.py
+++ b/packages/server/src/repowise/server/routers/code_health/findings_routes.py
@@ -2,7 +2,9 @@
from __future__ import annotations
-from fastapi import Depends, HTTPException, Query, Request
+import json
+
+from fastapi import Depends, HTTPException, Query, Request, Response
from pydantic import BaseModel, Field
from sqlalchemy.ext.asyncio import AsyncSession
@@ -29,6 +31,9 @@ from .statuses import (
parse_status_filter,
)
+#: The findings list's held-back counts (see ``list_health_findings``).
+GATED_HEADER = "X-Repowise-Gated"
+
@router.get(
"/api/repos/{repo_id}/health/findings",
@@ -36,6 +41,7 @@ from .statuses import (
)
async def list_health_findings(
repo_id: str,
+ response: Response,
biomarker_type: str | None = Query(None),
file_path: str | None = Query(None),
min_severity: str | None = Query(None, description="Severity floor"),
@@ -108,6 +114,13 @@ async def list_health_findings(
if parse_counts(counts) == "code_shape":
findings = split_by_origin(findings)[0]
shown = findings[:limit]
+ # The body is a list, so what a language gate or file hold left out rides
+ # in a header: ``{key: {count, reason}}``, absent when nothing was held.
+ gated = await crud.gated_health_counts(
+ session, repo_id, file_path=file_path, include_unverified=include_unverified
+ )
+ if gated:
+ response.headers[GATED_HEADER] = json.dumps(gated, separators=(",", ":"))
# Measured over every open finding on each file, whatever this list kept.
reasons = await crud.health_finding_priorities(session, repo_id, shown)
return await _attach_symbol_ids(
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 2d5a4b352..ac5f70dd3 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
@@ -74,17 +74,28 @@ async def health_overview(
# worst-first ranking, and the findings read is the most expensive of the
# two — so the route was paying for each of them twice per request.
metrics = await crud.get_health_metrics(session, repo_id)
+ # Live rows, before ``project`` wraps them: what the file holds read.
+ files = {m.file_path: m for m in metrics}
findings = await crud.get_health_findings(session, repo_id, include_unverified=True)
metrics, findings = narrow(scope, metrics, findings)
# Every figure below is computed from these two lists, so projecting here
# is what keeps the headline, the distribution, the hotspot figure and the
# work the page lists all describing the same thing.
metrics, scored_findings, unscored = project(counts, metrics, findings)
- findings, gated = split_gated(
+ # The KPIs count what the scores counted: language gates only. The lists
+ # below also leave out what a file hold keeps back, and ``gated`` says so.
+ kpi_findings, _ = split_gated(
"health", scored_findings, kind="biomarker_type", include_unverified=include_unverified
)
+ findings, gated = split_gated(
+ "health",
+ scored_findings,
+ kind="biomarker_type",
+ include_unverified=include_unverified,
+ files=files,
+ )
summary = await crud.get_health_summary(
- session, repo_id, metrics=metrics, findings=findings
+ session, repo_id, metrics=metrics, findings=kpi_findings
)
# Recomputed from the metrics already loaded rather than read off the latest
@@ -108,7 +119,7 @@ async def health_overview(
summary = {
**summary,
"hotspot_health": hotspot_health_value,
- "severity_breakdown": severity_breakdown(findings),
+ "severity_breakdown": severity_breakdown(kpi_findings),
# Echoed so a surface labels what it was sent rather than what it
# asked for; the two differ while a request is in flight.
"counts": counts,
diff --git a/packages/server/src/repowise/server/routers/files.py b/packages/server/src/repowise/server/routers/files.py
index 7da08a131..4964a02ed 100644
--- a/packages/server/src/repowise/server/routers/files.py
+++ b/packages/server/src/repowise/server/routers/files.py
@@ -19,7 +19,7 @@ from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.analysis.dead_code.deletion_gate import effective_safe_to_delete
-from repowise.core.analysis.finding_registry import excluded_types
+from repowise.core.analysis.finding_registry import excluded_types, split_gated
from repowise.core.analysis.health.aggregation import NLOC_NULL_REASON
from repowise.core.analysis.health.signals import file_signals
from repowise.core.analysis.health.trends import file_trend
@@ -303,7 +303,17 @@ async def file_detail(
)
# --- Health -----------------------------------------------------------
- findings = await crud.get_health_findings(session, repo_id, file_path=file_path)
+ findings = await crud.get_health_findings(
+ session, repo_id, file_path=file_path, include_unverified=True
+ )
+ # The score counts every finding; one a gate or file hold keeps back is left
+ # out of the list and breakdown, and ``gated`` says how many and why.
+ findings, gated = split_gated(
+ "health",
+ findings,
+ kind="biomarker_type",
+ files={metric.file_path: metric} if metric is not None else None,
+ )
snapshots = await crud.list_health_snapshots(
session, repo_id, limit=crud.FILE_TREND_SNAPSHOT_WINDOW
)
@@ -316,6 +326,7 @@ async def file_detail(
else None
),
"findings": [_finding_dict(f, slim=slim) for f in findings],
+ "gated": gated,
"trend": _file_trend_to_dict(file_trend(snapshots, file_path)),
"signals": _file_signals_to_dict(file_signals(git_meta, degrees)),
}
diff --git a/packages/server/src/repowise/server/routers/overview.py b/packages/server/src/repowise/server/routers/overview.py
index b3212e9f9..34ef2cd10 100644
--- a/packages/server/src/repowise/server/routers/overview.py
+++ b/packages/server/src/repowise/server/routers/overview.py
@@ -281,7 +281,9 @@ async def overview_summary(
# defect-accuracy stat both want every per-file row, and letting each fetch
# its own pulled the whole table twice per page load.
health_metrics = await crud.get_health_metrics(session, repo_id)
- findings = await crud.get_health_findings(session, repo_id)
+ # Every figure here is a KPI the scores counted, so the file-held rows stay
+ # in; ``health.gated`` says what the finding lists leave out.
+ findings = await crud.get_health_findings(session, repo_id, file_holds=False)
health_summary = await crud.get_health_summary(
session, repo_id, metrics=health_metrics, findings=findings
)
@@ -522,6 +524,8 @@ async def overview_summary(
# The findings' count vocabulary, which the Code Health page and the
# agent surfaces report too; ``open_findings`` stays for older readers.
"finding_counts": (await unit_counts(session, repo_id, "findings")).as_dict(),
+ # Why the finding lists hold some of those back, by language or file hold.
+ "gated": await crud.gated_health_counts(session, repo_id),
# The two co-equal pillars surfaced alongside the defect headline.
"maintainability_average": health_summary.get("maintainability_average"),
"performance_average": health_summary.get("performance_average"),
diff --git a/tests/unit/change_health/test_held_origins.py b/tests/unit/change_health/test_held_origins.py
new file mode 100644
index 000000000..0ec7a356e
--- /dev/null
+++ b/tests/unit/change_health/test_held_origins.py
@@ -0,0 +1,23 @@
+"""A change to vendored code is held back from the health delta by reason,
+as every other health surface holds its findings back."""
+
+from __future__ import annotations
+
+from repowise.core.analysis.change_health.service import ChangeHealthDeltaService, DeltaRequest
+
+from .conftest import python_complex
+
+
+def test_a_vendored_file_is_excluded_by_reason(make_repo):
+ repo = make_repo()
+ repo.commit("seed", {"vendor/lib.py": "x = 1\n", "app.py": "y = 1\n"})
+ repo.commit(
+ "edit",
+ {"vendor/lib.py": python_complex("tangle", 16), "app.py": python_complex("knot", 16)},
+ )
+
+ service = ChangeHealthDeltaService(repo_path=str(repo.path))
+ delta = service.compare(DeltaRequest(str(repo.path), "HEAD"))
+
+ assert delta.skipped.get("vendor/lib.py") == "vendored"
+ assert {f.path for f in delta.findings} == {"app.py"}
diff --git a/tests/unit/health/test_refactoring_move_method.py b/tests/unit/health/test_refactoring_move_method.py
index 9b5926dfb..e8c3362d3 100644
--- a/tests/unit/health/test_refactoring_move_method.py
+++ b/tests/unit/health/test_refactoring_move_method.py
@@ -399,6 +399,83 @@ def test_method_calling_an_inherited_member_or_in_a_trait_impl_does_not_move():
assert _detect_java(_java_envy_graph(), classes=[cls]) == []
+_JAVA_SERVICE = b"""
+@Service
+public class C {
+ private final ServerConfigRepository repository;
+
+ public C(ServerConfigRepository repository) {
+ this.repository = repository;
+ }
+
+ public T envious(T config) {
+ if (config.alpha() == null) {
+ config.beta("default");
+ }
+ config.gamma();
+ return repository.save(config);
+ }
+
+ public T stateless(T config) {
+ config.alpha();
+ config.beta("x");
+ return config.gamma();
+ }
+}
+"""
+
+
+def test_service_method_using_its_injected_field_does_not_move():
+ # A service method reading the repository its constructor injected, by bare
+ # name, stays: moving it onto the entity would carry persistence into it.
+ from repowise.core.analysis.health.complexity.walker import walk_file
+
+ classes = walk_file("C.java", "java", _JAVA_SERVICE).classes
+ assert "envious" in classes[0].field_readers
+ assert "stateless" not in classes[0].field_readers
+ g = _java_envy_graph()
+ g.nodes["C.java::C.envious"]["start_line"] = 10
+ assert _detect_java(g, classes=classes) == []
+ # Control: the same envy from a method that touches no field still fires.
+ g = _java_envy_graph(method="stateless")
+ g.nodes["C.java::C.stateless"]["start_line"] = 18
+ assert len(_detect_java(g, classes=classes)) == 1
+
+
+def test_static_logger_is_not_state_but_a_getter_is():
+ # A ``static final`` logger is class-level, not the instance's state, so
+ # logging does not bind a method; a getter reads a field and does.
+ from repowise.core.analysis.health.complexity.walker import walk_file
+
+ source = b"""
+public class C {
+ private static final Logger LOG = LoggerFactory.getLogger(C.class);
+ private final Repo repo;
+ public C(Repo repo) { this.repo = repo; }
+ public Repo getRepo() { return repo; }
+ public void logs(T t) { LOG.info("x"); t.alpha(); t.beta(); }
+}
+"""
+ readers = walk_file("C.java", "java", source).classes[0].field_readers
+ assert "getRepo" in readers and "logs" not in readers
+
+
+def test_go_emits_no_classes_so_receivers_are_not_read():
+ # Ceiling: Go methods attach to a type through an external receiver, and
+ # the class analysis emits no Go classes, so ``field_readers`` cannot bind
+ # a Go method to its struct's fields. Move Method keeps its other gates
+ # there (see ``languages.py`` on a receiver-aware grouping pass).
+ from repowise.core.analysis.health.complexity.walker import walk_file
+
+ source = b"""package p
+
+type Svc struct{ repo Repo }
+
+func (s *Svc) Uses(t T) { s.repo.Save(t) }
+"""
+ assert walk_file("svc.go", "go", source).classes == []
+
+
# ---- keyword modifiers and partial classes (C#, Kotlin, VB.NET) ------------
diff --git a/tests/unit/persistence/test_refactoring_test_file_hold.py b/tests/unit/persistence/test_refactoring_test_file_hold.py
new file mode 100644
index 000000000..ffa374547
--- /dev/null
+++ b/tests/unit/persistence/test_refactoring_test_file_hold.py
@@ -0,0 +1,116 @@
+"""Refactoring plans and opportunities on test files are held back on every
+plan surface, as Fix first already leaves them out, and each read that counts
+what it held back says so under ``test``.
+
+Mirrors the JVM audit: ``scope=all`` and the plan lists served extract_method
+plans on ``src/test`` and ``internalClusterTest`` files.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.analysis.finding_registry import FILE_HOLDS
+from repowise.core.analysis.health.refactoring import RefactoringSuggestion
+from repowise.core.persistence.crud.analysis import (
+ get_refactoring_suggestions,
+ save_refactoring_suggestions,
+)
+from tests.unit.persistence.helpers import insert_repo
+
+_TEST = "src/test/java/org/acme/HeaderValidatorTests.java"
+_PROD = "src/main/java/org/acme/HeaderValidator.kt"
+
+
+def _plan(path: str) -> RefactoringSuggestion:
+ return RefactoringSuggestion(
+ refactoring_type="extract_method",
+ file_path=path,
+ target_symbol="validate",
+ line_start=10,
+ line_end=60,
+ plan={},
+ evidence={},
+ impact_delta=1.0,
+ effort_bucket="S",
+ blast_radius={},
+ confidence="high",
+ source_biomarker="complex_method",
+ )
+
+
+async def _seed(session) -> str:
+ from repowise.core.analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION
+ from repowise.core.persistence.crud import upsert_health_metrics
+ from repowise.core.persistence.models import RefactoringOpportunity
+
+ repo = await insert_repo(session)
+ await upsert_health_metrics(
+ session,
+ repo.id,
+ [
+ {"file_path": _TEST, "score": 5.0, "nloc": 200, "is_test": True},
+ {"file_path": _PROD, "score": 5.0, "nloc": 200, "is_test": False},
+ ],
+ )
+ await save_refactoring_suggestions(session, repo.id, [_plan(_TEST), _plan(_PROD)])
+ session.add_all(
+ RefactoringOpportunity(
+ repository_id=repo.id,
+ opportunity_id=f"refop_{i}",
+ refactoring_model_version=REFACTORING_MODEL_VERSION,
+ rank_position=i,
+ queue_position=i,
+ rank_score=1.0,
+ lead_biomarker="complex_method",
+ judgment_steps=0,
+ evidence_total=0,
+ affected_files_total=1,
+ details_json="{}",
+ file_path=path,
+ recoverable_health=1.0,
+ step_count=1,
+ lead_refactoring_type="extract_method",
+ confidence="high",
+ effort_bucket="S",
+ mechanical_steps=1,
+ status="open",
+ queue_eligible=path == _PROD,
+ queue_reason=None if path == _PROD else "test",
+ )
+ for i, path in enumerate((_TEST, _PROD))
+ )
+ await session.commit()
+ return repo.id
+
+
+async def test_plan_lists_hold_back_test_files(async_session):
+ from repowise.core.persistence.crud.analysis.refactoring import gated_plan_counts
+
+ rid = await _seed(async_session)
+ assert [p.file_path for p in await get_refactoring_suggestions(async_session, rid)] == [_PROD]
+ assert await gated_plan_counts(async_session, rid) == {
+ "test": {"count": 1, "reason": FILE_HOLDS["test"]}
+ }
+ opted = await get_refactoring_suggestions(async_session, rid, include_unverified=True)
+ assert {p.file_path for p in opted} == {_TEST, _PROD}
+
+
+async def test_opportunity_lists_and_counts_hold_back_test_files(async_session):
+ from repowise.core.persistence.crud.analysis.queue_counts import unit_counts
+ from repowise.core.persistence.crud.analysis.refactoring_opportunities import (
+ gated_opportunity_counts,
+ list_refactoring_opportunities,
+ )
+
+ rid = await _seed(async_session)
+ # ``scope=all`` reads the whole open inventory, eligible or not.
+ rows, total = await list_refactoring_opportunities(async_session, rid)
+ assert [r.file_path for r in rows] == [_PROD] and total == 1
+ assert (await gated_opportunity_counts(async_session, rid))["test"]["count"] == 1
+ counts = (await unit_counts(async_session, rid, "plans")).as_dict()
+ assert counts["gated"] == 1
+ rows, total = await list_refactoring_opportunities(async_session, rid, include_unverified=True)
+ assert total == 2
diff --git a/tests/unit/server/mcp/test_file_holds.py b/tests/unit/server/mcp/test_file_holds.py
new file mode 100644
index 000000000..41dcda7c2
--- /dev/null
+++ b/tests/unit/server/mcp/test_file_holds.py
@@ -0,0 +1,215 @@
+"""File holds: a health finding on a vendored or generated file, or a history
+marker on a test file, is held back on every default surface, whatever the
+language, and each surface says how many and why.
+
+Mirrors the runtime audit (findings under ``src/native/external`` served
+although the index stores ``code_origin = vendored``) and the PowerToys one
+(``ownership_risk`` and ``change_entropy`` served on unit-test files).
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.analysis.finding_registry import FILE_HOLDS, file_hold, split_gated
+
+_VENDORED = "src/external/brotli/static_dict.py"
+_GENERATED = "src/proto/api_pb2.py"
+_TEST = "tests/test_fuzzy_matcher.py"
+
+
+def test_file_hold_reads_origin_and_test_flag():
+ assert file_hold("health", "large_method", "vendored", False) == "vendored"
+ assert file_hold("health", "complex_method", "generated", None) == "generated"
+ assert file_hold("health", "ownership_risk", "test", True) == "test_history"
+ assert file_hold("health", "change_entropy", "test", True) == "test_history"
+ # A code-shape finding on a test file is still served.
+ assert file_hold("health", "complex_method", "test", True) is None
+ # A history marker on production code is still served.
+ assert file_hold("health", "ownership_risk", "production", False) is None
+ # Unknown flag (row written before the column) is not held.
+ assert file_hold("health", "ownership_risk", None, None) is None
+ # Other layers are untouched.
+ assert file_hold("dead_code", "unreachable_file", "vendored", False) is None
+
+
+def test_split_gated_applies_file_holds_with_their_reason():
+ rows = [
+ {"file_path": _VENDORED, "biomarker_type": "large_method"},
+ {"file_path": _TEST, "biomarker_type": "ownership_risk"},
+ {"file_path": _TEST, "biomarker_type": "complex_method"},
+ {"file_path": "src/app.py", "biomarker_type": "ownership_risk"},
+ ]
+ files = {
+ _VENDORED: SimpleNamespace(code_origin="vendored", is_test=False),
+ _TEST: SimpleNamespace(code_origin="test", is_test=True),
+ "src/app.py": SimpleNamespace(code_origin="production", is_test=False),
+ }
+ shown, gated = split_gated(
+ "health", rows, kind="biomarker_type", get=lambda r, k: r[k], files=files
+ )
+ assert [(r["file_path"], r["biomarker_type"]) for r in shown] == [
+ (_TEST, "complex_method"),
+ ("src/app.py", "ownership_risk"),
+ ]
+ assert gated == {
+ "vendored": {"count": 1, "reason": FILE_HOLDS["vendored"]},
+ "test_history": {"count": 1, "reason": FILE_HOLDS["test_history"]},
+ }
+ # Without the metric rows nothing is held by file (unknown is not a hold).
+ assert len(split_gated("health", rows, kind="biomarker_type", get=lambda r, k: r[k])[0]) == 4
+ assert split_gated(
+ "health", rows, kind="biomarker_type", get=lambda r, k: r[k], files=files,
+ include_unverified=True,
+ ) == (rows, {})
+
+
+async def _seed(session, rid: str) -> None:
+ from repowise.core.persistence.crud import upsert_health_findings, upsert_health_metrics
+
+ def metric(path: str, origin: str, is_test: bool) -> dict:
+ return {
+ "file_path": path,
+ "score": 4.0,
+ "max_ccn": 25,
+ "max_nesting": 5,
+ "nloc": 300,
+ "has_test_file": False,
+ "module": "x",
+ "code_origin": origin,
+ "is_test": is_test,
+ }
+
+ def finding(path: str, kind: str, impact: float) -> dict:
+ return {
+ "file_path": path,
+ "biomarker_type": kind,
+ "severity": "high",
+ "function_name": "run",
+ "line_start": 1,
+ "line_end": 90,
+ "details": {},
+ "health_impact": impact,
+ "reason": f"{kind} on {path}",
+ }
+
+ await upsert_health_metrics(
+ session,
+ rid,
+ [
+ metric(_VENDORED, "vendored", False),
+ metric(_GENERATED, "generated", False),
+ metric(_TEST, "test", True),
+ ],
+ )
+ await upsert_health_findings(
+ session,
+ rid,
+ [
+ finding(_VENDORED, "large_method", 2.0),
+ finding(_GENERATED, "complex_method", 2.0),
+ finding(_TEST, "ownership_risk", 1.0),
+ finding(_TEST, "change_entropy", 1.0),
+ finding(_TEST, "complex_method", 1.0),
+ ],
+ file_paths=[_VENDORED, _GENERATED, _TEST],
+ )
+ await session.commit()
+
+
+async def test_crud_reader_holds_back_by_file(session, health_data):
+ from repowise.core.persistence.crud import get_health_findings
+
+ await _seed(session, health_data)
+ served = {(f.file_path, f.biomarker_type) for f in await get_health_findings(session, health_data)}
+ assert not {p for p, _ in served} & {_VENDORED, _GENERATED}
+ assert (_TEST, "complex_method") in served
+ assert not {(_TEST, "ownership_risk"), (_TEST, "change_entropy")} & served
+ assert "src/auth/service.py" in {p for p, _ in served}
+
+ opted = {
+ (f.file_path, f.biomarker_type)
+ for f in await get_health_findings(session, health_data, include_unverified=True)
+ }
+ assert {(_VENDORED, "large_method"), (_TEST, "ownership_risk")} <= opted
+
+
+async def test_get_health_holds_back_by_file_and_says_so(setup_mcp, session, health_data):
+ from repowise.server.mcp_server import get_health
+
+ await _seed(session, health_data)
+
+ default = await get_health(only=["top_findings"], limit=50)
+ rows = default["top_findings"] + default.get("test_findings", [])
+ files = {f["file_path"] for f in rows}
+ assert not files & {_VENDORED, _GENERATED}
+ # Compact: a count per hold, no reason text while findings are listed.
+ gated = default["_meta"]["gated"]
+ assert gated["health"] == {"vendored": 1, "generated": 1, "test_history": 2}
+ assert "reasons" not in gated
+
+ targeted = await get_health(targets=[_VENDORED])
+ assert not targeted.get("findings")
+ # Nothing listed: the reason comes once, so the empty list is explained.
+ assert targeted["_meta"]["gated"]["health"] == {"vendored": 1}
+ assert targeted["_meta"]["gated"]["reasons"] == {"vendored": FILE_HOLDS["vendored"]}
+
+
+def _no_holds(monkeypatch) -> None:
+ from repowise.core.analysis import finding_registry
+ from repowise.core.persistence.crud.analysis import shown as shown_module
+
+ monkeypatch.setattr(shown_module, "_file_holds", lambda *a, **k: [])
+ monkeypatch.setattr(finding_registry, "row_hold", lambda *a, **k: None)
+
+
+async def test_get_health_kpis_and_worst_files_ignore_holds(
+ setup_mcp, session, health_data, monkeypatch
+):
+ # The holds shorten finding lists; the KPIs and the worst-file order read
+ # what the scores counted, so they must not move.
+ from repowise.server.mcp_server import get_health
+
+ await _seed(session, health_data)
+ held = await get_health(only=["kpis", "worst_files"])
+ _no_holds(monkeypatch)
+ plain = await get_health(only=["kpis", "worst_files"])
+ assert held["kpis"] == plain["kpis"]
+ assert held["worst_files"] == plain["worst_files"]
+
+
+async def test_default_get_health_does_not_grow(setup_mcp, session, health_data, monkeypatch):
+ # No gated language and no held row in the seeded repository: the default
+ # response is byte-identical with and without the holds.
+ from repowise.server.mcp_server import get_health
+
+ def size(result: dict) -> int:
+ result = {**result, "_meta": {k: v for k, v in result["_meta"].items() if k != "timing_ms"}}
+ return len(json.dumps(result, sort_keys=True, default=str))
+
+ with_holds = size(await get_health())
+ _no_holds(monkeypatch)
+ assert size(await get_health()) == with_holds
+
+
+async def test_default_get_health_grows_by_a_count_per_hold(
+ setup_mcp, session, health_data, monkeypatch
+):
+ # With held rows the list loses them and ``_meta.gated`` gains one integer
+ # per hold key: never a reason sentence while findings are listed.
+ from repowise.server.mcp_server import get_health
+
+ await _seed(session, health_data)
+ result = await get_health()
+ gated = result["_meta"]["gated"]
+ assert set(gated) == {"health", "opt_in"}
+ assert all(isinstance(v, int) for v in gated["health"].values())
+ assert len(json.dumps(gated["health"])) < 64
diff --git a/tests/unit/server/test_health_file_holds_routes.py b/tests/unit/server/test_health_file_holds_routes.py
new file mode 100644
index 000000000..c356978e3
--- /dev/null
+++ b/tests/unit/server/test_health_file_holds_routes.py
@@ -0,0 +1,148 @@
+"""File holds on the REST health surfaces: the lists leave held findings out
+and say why, while every score and KPI reads exactly what it read before.
+
+Seeds one vendored file, one test file carrying a history marker and one
+production file, all Python, so no language gate is involved.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from httpx import AsyncClient
+
+from repowise.core.analysis.finding_registry import FILE_HOLDS
+from repowise.core.persistence import crud
+from repowise.core.persistence.crud.analysis import shown as shown_module
+from repowise.core.persistence.database import get_session
+from tests.unit.server.conftest import create_test_repo
+
+_VENDORED = "third_party/lib/minified.py"
+_TEST = "tests/test_app.py"
+_PROD = "src/app.py"
+
+
+def _metric(path: str, score: float, origin: str, is_test: bool) -> dict:
+ return {
+ "file_path": path,
+ "score": score,
+ "defect_score": score,
+ "max_ccn": 20,
+ "max_nesting": 4,
+ "nloc": 200,
+ "has_test_file": False,
+ "module": path.split("/")[0],
+ "code_origin": origin,
+ "is_test": is_test,
+ }
+
+
+def _finding(path: str, kind: str, impact: float) -> dict:
+ return {
+ "file_path": path,
+ "biomarker_type": kind,
+ "severity": "high",
+ "function_name": "run",
+ "line_start": 1,
+ "line_end": 80,
+ "details": {},
+ "health_impact": impact,
+ "reason": f"{kind} on {path}",
+ }
+
+
+async def _seed(app, repo_id: str) -> None:
+ async with get_session(app.state.session_factory) as session:
+ await crud.save_health_metrics(
+ session,
+ repo_id,
+ [
+ _metric(_VENDORED, 2.0, "vendored", False),
+ _metric(_TEST, 7.0, "test", True),
+ _metric(_PROD, 5.0, "production", False),
+ ],
+ )
+ await crud.save_health_findings(
+ session,
+ repo_id,
+ [
+ _finding(_VENDORED, "large_method", 4.0),
+ _finding(_VENDORED, "complex_method", 3.0),
+ _finding(_TEST, "ownership_risk", 1.0),
+ _finding(_PROD, "complex_method", 2.0),
+ ],
+ )
+
+
+def _no_holds(monkeypatch) -> None:
+ monkeypatch.setattr(shown_module, "_file_holds", lambda *a, **k: [])
+ from repowise.core.analysis import finding_registry
+
+ monkeypatch.setattr(finding_registry, "row_hold", lambda *a, **k: None)
+
+
+async def test_file_page_lists_no_held_finding_and_says_why(client: AsyncClient, app) -> None:
+ repo = await create_test_repo(client)
+ await _seed(app, repo["id"])
+ page = (await client.get(f"/api/repos/{repo['id']}/files/{_VENDORED}")).json()
+ assert page["health"]["findings"] == []
+ assert page["health"]["gated"] == {"vendored": {"count": 2, "reason": FILE_HOLDS["vendored"]}}
+ assert page["health"]["metric"]["score"] == 2.0
+
+
+async def test_findings_list_header_and_files_list_say_what_is_held(
+ client: AsyncClient, app
+) -> None:
+ repo = await create_test_repo(client)
+ await _seed(app, repo["id"])
+ resp = await client.get(f"/api/repos/{repo['id']}/health/findings")
+ assert {f["file_path"] for f in resp.json()} == {_PROD}
+ gated = json.loads(resp.headers["X-Repowise-Gated"])
+ assert gated["vendored"]["count"] == 2 and gated["test_history"]["count"] == 1
+
+ files = (await client.get(f"/api/repos/{repo['id']}/health/files")).json()
+ rows = {r["file_path"]: r for r in files["files"]}
+ assert rows[_VENDORED]["held_reason"] == FILE_HOLDS["vendored"]
+ assert "held_reason" not in rows[_PROD]
+ assert files["gated"]["vendored"]["count"] == 2
+
+
+async def test_scores_and_kpis_do_not_change_with_the_holds(
+ client: AsyncClient, app, monkeypatch
+) -> None:
+ repo = await create_test_repo(client)
+ await _seed(app, repo["id"])
+
+ def kpis(overview: dict, summary: dict) -> tuple:
+ s = overview["summary"]
+ h = summary["health"]
+ return (
+ s.get("average_health"),
+ s.get("worst_performer_path"),
+ s.get("open_findings"),
+ s.get("severity_breakdown"),
+ h.get("average_health"),
+ h.get("worst_performer_path"),
+ h.get("open_findings"),
+ h.get("severity_breakdown"),
+ )
+
+ held = kpis(
+ (await client.get(f"/api/repos/{repo['id']}/health/overview")).json(),
+ (await client.get(f"/api/repos/{repo['id']}/overview-summary")).json(),
+ )
+ async with get_session(app.state.session_factory) as session:
+ held_summary = await crud.get_health_summary(session, repo["id"])
+ _no_holds(monkeypatch)
+ plain = kpis(
+ (await client.get(f"/api/repos/{repo['id']}/health/overview")).json(),
+ (await client.get(f"/api/repos/{repo['id']}/overview-summary")).json(),
+ )
+ async with get_session(app.state.session_factory) as session:
+ plain_summary = await crud.get_health_summary(session, repo["id"])
+ assert held == plain
+ assert held_summary == plain_summary