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.

feat(health): measure test mock saturation without moving any score (#2317)

Raghav Chamadiya7014cfaee845
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.md
index 741fb8aa3..a91a69aba 100644
--- a/docs/layers/CODE_HEALTH.md
+++ b/docs/layers/CODE_HEALTH.md
@@ -387,9 +387,10 @@ Reports:
## Three health signals: defect risk, maintainability, and performance
-The three signals are computed from the same marker stream by one shared scoring
-kernel against independent weight, category and cap tables. They are co-equal
-views, **never blended into a single number**.
+The three scored signals are computed from the same marker stream by one shared
+scoring kernel against independent weight, category and cap tables. They are
+co-equal views, **never blended into a single number**. A fourth dimension,
+`advisory`, carries markers that never score at all. See below.
**Defect risk** is the calibrated headline: the number on the dashboard ring,
the band, the badge, and every accuracy claim above.
@@ -416,6 +417,36 @@ identically: `summary.*_average` on the REST overview, `kpis.*` on MCP
`get_health`, per-file scores on every metric row, and a line each in `CLAUDE.md`
and `repowise status`.
+### The fourth dimension: `advisory`, which never scores
+
+Some things are worth measuring and impossible to calibrate. No defect corpus
+labels how much of a test is mock setup, so a mock-density marker has no
+calibration story and never will. Weighting it anyway would move a number that
+claims to predict bugs using evidence that says nothing about bugs.
+
+`advisory` is where those markers live. It is deliberately **not** one of the
+three scored dimensions: there is no weight table, category or cap keyed on it,
+so "never deducts" is structural rather than a promise. Its findings carry a
+`health_impact` of exactly `0.0`, are excluded from every impact-ranked work
+queue, are never counted in a change's introduced/worsened totals, and can never
+make a review verdict blocking.
+
+| Marker | Languages | What it measures |
+|---|---|---|
+| `mock_saturated_test` | Python | Mock-setup statements per assertion in a test function |
+
+A marker earns weight by clearing the house precision bar (roughly 70%
+hand-labelled) on a real corpus. `mock_saturated_test` has not: a 32-finding
+hand-labelled sample scored 44% at its loosest useful gate and 67% at the gate it
+ships with. It stays advisory until two false-positive families are separated:
+value-object builders named `Fake*` passed as input to real logic, and boundary
+isolation where the assertion reads a real artifact. Telling
+either from genuine saturation needs to know whether an assertion observes a
+double or production output, which is a dataflow question the pass does not ask.
+
+Per-language coverage and why Go is blocked:
+[LANGUAGE_SUPPORT.md](LANGUAGE_SUPPORT.md#code-health-coverage).
+
## Performance risk
The pillar's core is **`io_in_loop`** — a database call, network request,
diff --git a/docs/layers/LANGUAGE_SUPPORT.md b/docs/layers/LANGUAGE_SUPPORT.md
index 7190e535a..dc7d8e915 100644
--- a/docs/layers/LANGUAGE_SUPPORT.md
+++ b/docs/layers/LANGUAGE_SUPPORT.md
@@ -355,29 +355,40 @@ Health markers run off a per-language walker map that is **independent** of
`.scm` parsing: a language can parse perfectly for the graph and still need this
map before markers fire. This table is why a language is Full rather than Good.
-| Language | Complexity / nesting | Class metrics | Assertion smells | Extract Method | Performance risk |
-|----------|:---:|:---:|:---:|:---:|:---:|
-| Python | ✅ | ✅ | ✅ | ✅ | ✅ |
-| TypeScript / JavaScript | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Svelte · Vue | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Java | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Go | ✅ | n/a | ✅ | ✅ | ✅ |
-| Rust | ✅ | ✅ | ✅ | ✅ | ✅ |
-| C++ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| C# | ✅ | ✅ | ✅ | later | ✅ |
-| Kotlin | ✅ | ✅ | ✅ | blocked | ✅ |
-| Scala | ✅ | ✅ | ✅ | later | ✅ |
-| Ruby | ✅ | ✅ | ✅ | later | ✅ |
-| Dart | ✅ | n/a | ✅ | later | ✅ |
-| Object Pascal | ✅ | n/a | later | later | n/a |
-| Razor | ✅ | n/a | n/a | later | ✅ |
-| Shell | ✅ | n/a | n/a | n/a | n/a |
+| Language | Complexity / nesting | Class metrics | Assertion smells | Mock saturation | Extract Method | Performance risk |
+|----------|:---:|:---:|:---:|:---:|:---:|:---:|
+| Python | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| TypeScript / JavaScript | ✅ | ✅ | ✅ | later | ✅ | ✅ |
+| Svelte · Vue | ✅ | ✅ | ✅ | later | ✅ | ✅ |
+| Java | ✅ | ✅ | ✅ | later | ✅ | ✅ |
+| Go | ✅ | n/a | ✅ | blocked | ✅ | ✅ |
+| Rust | ✅ | ✅ | ✅ | later | ✅ | ✅ |
+| C++ | ✅ | ✅ | ✅ | later | ✅ | ✅ |
+| C# | ✅ | ✅ | ✅ | later | later | ✅ |
+| Kotlin | ✅ | ✅ | ✅ | later | blocked | ✅ |
+| Scala | ✅ | ✅ | ✅ | later | later | ✅ |
+| Ruby | ✅ | ✅ | ✅ | later | later | ✅ |
+| Dart | ✅ | n/a | ✅ | later | later | ✅ |
+| Object Pascal | ✅ | n/a | later | n/a | later | n/a |
+| Razor | ✅ | n/a | n/a | n/a | later | ✅ |
+| Shell | ✅ | n/a | n/a | n/a | n/a | n/a |
Every cell is a deliberate call, not an oversight: a language reaches a dialect
or it stays silent, and an `n/a` records a metric the language cannot carry
rather than one nobody got to. Kotlin's Extract Method is **blocked on the
grammar**, not unscheduled.
+**Mock saturation** measures a test's mock setup against its assertions, so it
+needs both a mock vocabulary and a trustworthy assertion count. The vocabulary
+is one data row per language in
+`analysis/health/mocks/lexicon.py`; a language with no row produces no signal at
+all. Go is **blocked**, not unscheduled: its `assert_call_kinds` is best-effort
+for testify only, so idiomatic `t.Error` / `t.Fatal` tests are invisible to the
+shared assert/expect prefix match and every ratio computed from them would be
+wrong. Go needs its own assertion vocabulary before the marker can be honest
+there. The marker is advisory and never deducts. See
+[CODE_HEALTH.md](CODE_HEALTH.md).
+
Per-marker mechanics, every per-language precision ceiling and the reasoning
behind each `n/a`: [CODE_HEALTH.md](CODE_HEALTH.md) and
[architecture/language-support.md](../architecture/language-support.md).
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 cf339f88b..fba032e22 100644
--- a/packages/core/src/repowise/core/analysis/change_health/service.py
+++ b/packages/core/src/repowise/core/analysis/change_health/service.py
@@ -15,6 +15,7 @@ from dataclasses import dataclass
from ..health import HEALTH_ANALYZER_VERSION, HealthFindingData
from ..health.perf.causal import PERFORMANCE_MODEL_VERSION
+from ..health.scoring import ADVISORY_DIMENSION, is_advisory
from .analyzer import RevisionHealthAnalyzer, language_for, language_of
from .attribution import FindingAttributor, changed_symbols_for
from .identity import change_finding_id, finding_key, severity_rank
@@ -48,7 +49,7 @@ _WAIT_TIMEOUT_SECONDS = 30
#: Wait-then-retry rounds before a caller stops queueing and computes.
_CLAIM_ATTEMPTS = 2
-_DIMENSION_ORDER = {"defect": 0, "maintainability": 1, "performance": 2}
+_DIMENSION_ORDER = {"defect": 0, "maintainability": 1, "performance": 2, ADVISORY_DIMENSION: 3}
@dataclass(frozen=True, slots=True)
@@ -258,10 +259,19 @@ class ChangeHealthDeltaService:
matcher = FindingMatcher(rename)
# Both sides are restricted to the same comparable set, so an excluded
# file cannot contribute a one-sided "introduced" or "resolved".
+ # Advisory markers deduct nothing, so adding one is not a regression
+ # and removing one is not a fix. Dropped from BOTH sides before
+ # matching, so every counter derived from the match agrees.
base_findings = [
- f for f in base_run.findings if rename.get(f.file_path, f.file_path) in subject
+ f
+ for f in base_run.findings
+ if rename.get(f.file_path, f.file_path) in subject
+ and not is_advisory(f.biomarker_type)
]
- match = matcher.match(base_findings, head_run.findings_for(subject))
+ head_findings = [
+ f for f in head_run.findings_for(subject) if not is_advisory(f.biomarker_type)
+ ]
+ match = matcher.match(base_findings, head_findings)
by_file: dict[str, list[HealthFindingData]] = {}
for finding in head_run.findings_for(subject):
diff --git a/packages/core/src/repowise/core/analysis/health/aggregation.py b/packages/core/src/repowise/core/analysis/health/aggregation.py
index fee1305e3..238394976 100644
--- a/packages/core/src/repowise/core/analysis/health/aggregation.py
+++ b/packages/core/src/repowise/core/analysis/health/aggregation.py
@@ -22,6 +22,7 @@ from .scoring import (
SCORE_MAX,
biomarker_category,
biomarker_weight,
+ is_advisory,
severity_deduction,
)
@@ -140,9 +141,14 @@ def severity_breakdown(findings: Iterable[Any]) -> dict[str, int]:
``dict`` keeps the key it was built with — so the returned keys stay plain
strings even when every finding carried an enum. Do not "fix" that by
coercing: the wire shape depends on it.
+
+ Advisory findings are excluded so this agrees with ``open_findings``,
+ which is rendered beside it in the same payload.
"""
out = dict.fromkeys(SEVERITY_ORDER, 0)
for finding in findings:
+ if is_advisory(field(finding, "biomarker_type", "") or ""):
+ continue
severity = _severity_key(field(finding, "severity", None))
if severity in out:
out[severity] += 1
@@ -197,8 +203,12 @@ def score_breakdown(findings: Sequence[Any]) -> dict[str, Any]:
"""
per_category: dict[str, list[Any]] = {}
for finding in findings:
- category = biomarker_category(field(finding, "biomarker_type", None))
- per_category.setdefault(category, []).append(finding)
+ biomarker = field(finding, "biomarker_type", None)
+ # No deduction to explain. Left in, it reports a raw deduction the
+ # file never paid and a ``capped`` flag on an uncapped category.
+ if is_advisory(biomarker or ""):
+ continue
+ per_category.setdefault(biomarker_category(biomarker), []).append(finding)
categories: list[dict[str, Any]] = []
total_deduction = 0.0
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/mock_saturated_test.py b/packages/core/src/repowise/core/analysis/health/biomarkers/mock_saturated_test.py
new file mode 100644
index 000000000..acc9a2627
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/mock_saturated_test.py
@@ -0,0 +1,93 @@
+"""Mock Saturated Test: a test that mostly configures doubles.
+
+A test built almost entirely of mock setup, with a single assertion at the end,
+passes whatever the code under test does. It pins the shape of the collaboration
+the test itself wired up, so it goes green on code that is broken and stays
+green through the refactor that should have failed it.
+
+Fires on a **ratio**, never a count: a test with twelve doubles and twelve
+assertions is exercising a genuinely wide surface and is not the target. The
+target is a test whose setup dwarfs what it checks.
+
+**This marker is advisory and never deducts.** No defect corpus labels mock
+density, so there is no calibration story for it and there will not be one.
+See ``ADVISORY_DIMENSION`` in ``scoring.py``, and CODE_HEALTH.md for the
+measured precision and the false positives it does not separate.
+
+The vocabulary comes from Hora and Robbes, MSR '26
+(doi:10.1145/3793302.3793362). The paper defines no over-mocking threshold and
+names it future work, so the thresholds here are ours. Its 94% precision
+answers "does this commit introduce a mock?", which is an easier question than
+this one; never quote it for this marker.
+"""
+
+from __future__ import annotations
+
+from ..coverage import is_test_file
+from ..mocks.lexicon import mock_dialect
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+
+class MockSaturatedTestDetector:
+ name = "mock_saturated_test"
+ category = "test_quality"
+
+ # Hand-labelled over 32 findings: 44% at a floor of 4, 67% at 6. Precision
+ # follows the floor, not the ratio, so the floor does the work and the ratio
+ # only keeps wide integration tests out. Raise them rather than lower them.
+ _MIN_MOCK_SETUP = 6
+ _MIN_RATIO = 3.0
+ _HIGH_RATIO = 8.0 # setup:assertion at which the test is nearly all scaffolding
+
+ def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ if not is_test_file(ctx.file_path):
+ return []
+ prefixes = _name_prefixes(ctx.language)
+ out: list[BiomarkerResult] = []
+ for fn in ctx.function_metrics.values():
+ mocks = fn.mock_setup_count
+ asserts = fn.assertion_count
+ # No assertion at all means a fixture or a helper, not a saturated
+ # test. A mock factory with no assertions is correct code.
+ if mocks < self._MIN_MOCK_SETUP or asserts < 1:
+ continue
+ if prefixes and not fn.name.lower().startswith(prefixes):
+ continue
+ ratio = mocks / asserts
+ if ratio < self._MIN_RATIO:
+ continue
+ severity = Severity.MEDIUM if ratio >= self._HIGH_RATIO else Severity.LOW
+ out.append(
+ BiomarkerResult(
+ biomarker_type=self.name,
+ severity=severity,
+ function_name=fn.name,
+ line_start=fn.start_line,
+ line_end=fn.end_line,
+ details={
+ "function": fn.name,
+ "mock_setup_count": mocks,
+ "assertion_count": asserts,
+ "ratio": round(ratio, 2),
+ },
+ reason=(
+ f"{fn.name} runs {mocks} mock-setup statements "
+ f"against {asserts} assertion{'s' if asserts != 1 else ''}"
+ ),
+ )
+ )
+ return out
+
+
+def _name_prefixes(language: str) -> tuple[str, ...]:
+ """The dialect's test-name prefixes, or ``()`` when it declares none.
+
+ Empty is the honest answer for a language whose tests are anonymous
+ callbacks; the detector then leans on its assertion gate alone.
+ """
+ dialect = mock_dialect(language)
+ return dialect.test_name_prefixes if dialect is not None else ()
+
+
+BIOMARKER = MockSaturatedTestDetector()
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
index 64b548ece..5fd173d98 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
@@ -44,6 +44,7 @@ from .list_insert_zero_in_loop import ListInsertZeroInLoopDetector
from .lock_in_loop import LockInLoopDetector
from .low_cohesion import LowCohesionDetector
from .membership_test_against_list_in_loop import MembershipTestAgainstListInLoopDetector
+from .mock_saturated_test import MockSaturatedTestDetector
from .nested_complexity import NestedComplexityDetector
from .nested_loop_quadratic import NestedLoopQuadraticDetector
from .nested_loop_with_io import NestedLoopWithIoDetector
@@ -89,6 +90,8 @@ _DETECTOR_FACTORIES: list[type[Biomarker]] = [
LargeAssertionBlockDetector, # type: ignore[list-item]
DuplicatedAssertionBlockDetector, # type: ignore[list-item]
ErrorHandlingDetector, # type: ignore[list-item]
+ # Advisory dimension - measured, never deducts (scoring.ADVISORY_DIMENSION).
+ MockSaturatedTestDetector, # type: ignore[list-item]
# Performance dimension (advisory weight; bounded by the perf cap).
IoInLoopDetector, # type: ignore[list-item]
StringConcatInLoopDetector, # type: ignore[list-item]
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/assertions.py b/packages/core/src/repowise/core/analysis/health/complexity/assertions.py
index 246e35d86..0a15e03a2 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/assertions.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/assertions.py
@@ -1,10 +1,12 @@
"""Assertion-block detection (test-quality smells).
Finds runs of ≥2 consecutive assertion statements within a function body,
-recorded as ``(start_line, end_line, count)``. Opt-in per language via the
-``LanguageNodeMap`` ``assert_kinds`` / ``assert_call_kinds`` fields; a language
-that maps neither produces nothing (never a false positive). Consumed by the
-``large_assertion_block`` / ``duplicated_assertion_block`` biomarkers.
+recorded as ``(start_line, end_line, count)``, and the body's total assertion
+count. Opt-in per language via the ``LanguageNodeMap`` ``assert_kinds`` /
+``assert_call_kinds`` fields; a language that maps neither produces nothing
+(never a false positive). Consumed by the ``large_assertion_block`` /
+``duplicated_assertion_block`` biomarkers, and by ``mock_saturated_test``,
+which divides mock setup by the total.
"""
from __future__ import annotations
@@ -89,19 +91,32 @@ def _is_assertion_statement(stmt: Node, lmap: LanguageNodeMap) -> bool:
return call is not None and _callee_matches_assert(call)
-def _collect_assertion_blocks(body_node: Node, lmap: LanguageNodeMap) -> list[tuple[int, int, int]]:
- """Runs of ≥2 consecutive assertion statements within a function body.
-
- Each run is recorded as ``(start_line, end_line, count)``. Runs are
- found per statement-list (a block's direct children), so an assertion
- sequence broken by a non-assertion statement starts a new run. Nested
- function bodies are skipped — their assertions belong to them.
+def _collect_assertion_facts(
+ body_node: Node, lmap: LanguageNodeMap
+) -> tuple[list[tuple[int, int, int]], int]:
+ """``(blocks, total)`` assertion facts for one function body.
+
+ *blocks* are runs of ≥2 consecutive assertion statements, each recorded as
+ ``(start_line, end_line, count)``. Runs are found per statement-list (a
+ block's direct children), so an assertion sequence broken by a
+ non-assertion statement starts a new run. Nested function bodies are
+ skipped: their assertions belong to them.
+
+ *total* counts assertion **statements** only, at block level. The run scan
+ keeps scanning everywhere, which is a deliberate asymmetry: it feeds the
+ calibrated ``duplicated_assertion_block``, and narrowing it would change
+ scored findings. A run needs two siblings so it rarely fires off a statement
+ list, but a total counts each match on its own and would double-count every
+ assertion in a language whose ``assert_call_kinds`` is its plain call node.
+ Block level also makes it commensurable with ``mock_walk._count_body_setup``.
"""
if not lmap.assert_kinds and not lmap.assert_call_kinds:
- return []
+ return [], 0
blocks: list[tuple[int, int, int]] = []
+ total = 0
- def _scan_siblings(parent: Node) -> None:
+ def _scan_siblings(parent: Node, *, count_total: bool) -> None:
+ nonlocal total
run_start = 0
run_end = 0
run_count = 0
@@ -109,6 +124,8 @@ def _collect_assertion_blocks(body_node: Node, lmap: LanguageNodeMap) -> list[tu
if not child.is_named:
continue
if _is_assertion_statement(child, lmap):
+ if count_total:
+ total += 1
if run_count == 0:
run_start = child.start_point[0] + 1
run_end = child.end_point[0] + 1
@@ -121,11 +138,11 @@ def _collect_assertion_blocks(body_node: Node, lmap: LanguageNodeMap) -> list[tu
blocks.append((run_start, run_end, run_count))
def _visit(node: Node) -> None:
- _scan_siblings(node)
+ _scan_siblings(node, count_total=node is body_node or node.type in lmap.block_kinds)
for child in node.children:
if child.type in lmap.function_kinds:
- continue # nested fn — walked as its own entry
+ continue # nested fn, not collected as its own entry either
_visit(child)
_visit(body_node)
- return blocks
+ return blocks, total
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/languages.py b/packages/core/src/repowise/core/analysis/health/complexity/languages.py
index 37bfc152a..f1fa38dd7 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/languages.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/languages.py
@@ -199,6 +199,15 @@ class LanguageNodeMap:
# silently drop), so only truly expression-oriented grammars may map it.
statement_wrapper_kinds: frozenset[str] = frozenset()
+ # -- Decorators / annotations (mock-saturation pass) ---------------------
+ # * ``decorator_kinds`` -- the node a single ``@thing`` is parsed as.
+ # * ``decorated_definition_kinds`` -- the wrapper node HOLDING them when
+ # the grammar puts them outside the function node, as Python does.
+ # Grammars that keep them inside map the first alone.
+ # Both empty (the default) means no decorator signal.
+ decorator_kinds: frozenset[str] = frozenset()
+ decorated_definition_kinds: frozenset[str] = frozenset()
+
_PY = LanguageNodeMap(
function_kinds=frozenset({"function_definition", "async_function_definition"}),
@@ -232,6 +241,8 @@ _PY = LanguageNodeMap(
break_kinds=frozenset({"break_statement"}),
continue_kinds=frozenset({"continue_statement"}),
with_kinds=frozenset({"with_statement"}),
+ decorator_kinds=frozenset({"decorator"}),
+ decorated_definition_kinds=frozenset({"decorated_definition"}),
)
_TS = LanguageNodeMap(
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/mock_walk.py b/packages/core/src/repowise/core/analysis/health/complexity/mock_walk.py
new file mode 100644
index 000000000..4ffac7b37
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/complexity/mock_walk.py
@@ -0,0 +1,240 @@
+"""Per-function mock-setup counting (the numerator of mock saturation).
+
+Counts, for one function body, how many **statements** are mock setup rather
+than the test's actual work. The vocabulary is per-language data in
+``analysis/health/mocks/lexicon.py``; everything here is language-agnostic and
+driven by the ``LanguageNodeMap``, so adding a language is a lexicon row plus its
+node kinds.
+
+Two grammar shapes are handled here rather than per language, so that stays
+true: a call whose callee is one subtree (Python, TS) and a call that splits the
+name from its receiver into separate fields (Java, C#). A grammar that is
+neither would need this file, and that is worth knowing before promising a
+language it does not cover.
+
+Two rules keep the count honest. Statements, not tokens:
+``repo.load.return_value = MagicMock()`` is one act of setup though it matches
+twice. And an assertion is never setup, even when it reads a double
+(``mock.assert_called_once_with(...)``), so anything ambiguous counts against
+firing.
+
+A language that maps no ``block_kinds`` produces no count: without them a
+statement cannot be told from an intermediate node.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..mocks.lexicon import MOCK_IDENTIFIER_TOKENS, MockDialect
+from .assertions import _is_assertion_statement
+from .ast_utils import _IDENTIFIER_SUFFIX
+from .languages import LanguageNodeMap
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+# Whole-file precheck, so production code pays one substring scan and nothing
+# else. Matched against a lowercased copy, so casing never matters.
+_FILE_MARKERS: tuple[bytes, ...] = tuple(
+ sorted(tok.encode() for tok in (*MOCK_IDENTIFIER_TOKENS, "patch"))
+)
+
+
+def file_may_contain_mocks(source: bytes) -> bool:
+ """True when *source* is worth running the mock pass over.
+
+ A pure function of the file's bytes, so it is safe under the walk cache,
+ which keys on content and language and never on the path.
+ """
+ lowered = source.lower()
+ return any(marker in lowered for marker in _FILE_MARKERS)
+
+
+def _identifier_chain(node: Node) -> list[str]:
+ """Every identifier under *node*, lowercased, in document order.
+
+ Order is load-bearing: the last entry is the name being called, the rest
+ the receiver path. Argument lists are never descended into.
+ """
+ names: list[str] = []
+ stack: list[Node] = [node]
+ while stack:
+ cur = stack.pop()
+ if cur.type in ("argument_list", "arguments"):
+ continue
+ if cur.type.endswith(_IDENTIFIER_SUFFIX) and cur.text is not None:
+ names.append(cur.text.decode("utf-8", "replace").lower())
+ stack.extend(reversed(cur.children))
+ return names
+
+
+def _callee_names(call_node: Node) -> tuple[str, set[str]] | None:
+ """``(called_name, receiver_roots)`` for a call, or ``None``.
+
+ Two grammar shapes: a single callee subtree under ``function`` / ``macro``,
+ read rightmost-last so ``mock.patch(...)`` gives ``("patch", {"mock"})``; or
+ a ``name`` field beside an ``object`` field (Java, C#), where the callee is
+ not one node. Arguments are excluded in both.
+ """
+ name_node = call_node.child_by_field_name("name")
+ if name_node is not None:
+ # Split shape: the name IS the called name, the receiver is ``object``.
+ called = (name_node.text or b"").decode("utf-8", "replace").lower()
+ if not called:
+ return None
+ receiver = call_node.child_by_field_name("object")
+ return called, set(_identifier_chain(receiver)) if receiver is not None else set()
+
+ callee = call_node.child_by_field_name("function") or call_node.child_by_field_name("macro")
+ if callee is None:
+ named = [
+ c
+ for c in call_node.children
+ if c.is_named and c.type not in ("argument_list", "arguments")
+ ]
+ callee = named[0] if named else None
+ if callee is None:
+ return None
+ chain = _identifier_chain(callee)
+ if not chain:
+ return None
+ return chain[-1], set(chain[:-1])
+
+
+def _is_mock_call(call_node: Node, dialect: MockDialect) -> bool:
+ """True when *call_node* constructs, patches or configures a test double."""
+ names = _callee_names(call_node)
+ if names is None:
+ return False
+ called, roots = names
+ for root in roots:
+ methods = dialect.receiver_methods.get(root)
+ if methods is not None:
+ # A listed receiver is exhaustive about its own methods.
+ return called in methods
+ if any(token in name for name in (called, *roots) for token in MOCK_IDENTIFIER_TOKENS):
+ return True
+ if called in dialect.setup_callees or roots & dialect.setup_callees:
+ return True
+ if called in dialect.guarded_callees:
+ # A bare call, or a known mocking module. ``client.patch("/url")``
+ # is an HTTP request, not a mock.
+ return not roots or bool(roots & dialect.guard_roots)
+ return False
+
+
+def _is_config_assignment(stmt: Node, lmap: LanguageNodeMap, dialect: MockDialect) -> bool:
+ """True when *stmt* assigns to a double's configuration attribute."""
+ if not dialect.config_attributes:
+ return False
+ for node in (stmt, *(c for c in stmt.children if c.is_named)):
+ if node.type not in lmap.assignment_kinds:
+ continue
+ left = node.child_by_field_name("left")
+ if left is None:
+ continue
+ chain = _identifier_chain(left)
+ # The attribute needs a receiver, or a local named ``return_value``
+ # reads as mock configuration.
+ if len(chain) >= 2 and any(name in dialect.config_attributes for name in chain[1:]):
+ return True
+ return False
+
+
+def _contains_mock_call(node: Node, lmap: LanguageNodeMap, dialect: MockDialect) -> bool:
+ """True when *node*'s own expression contains a mock call.
+
+ Descends through the statement but stops at nested function bodies and at
+ nested blocks, whose statements are scanned in their own right.
+ """
+ stack: list[Node] = [node]
+ while stack:
+ cur = stack.pop()
+ if cur.type in lmap.call_kinds and _is_mock_call(cur, dialect):
+ return True
+ for child in cur.children:
+ if child.type in lmap.function_kinds or child.type in lmap.block_kinds:
+ continue
+ stack.append(child)
+ return False
+
+
+def _count_decorators(fn_node: Node, lmap: LanguageNodeMap, dialect: MockDialect) -> int:
+ """Mock-injecting decorators on *fn_node*'s signature.
+
+ ``@patch("a.b")`` injects a double exactly as a ``patch(...)`` call in the
+ body would. Grammars that park decorators on a wrapper node declare it via
+ ``decorated_definition_kinds``; the rest keep them inside the function node.
+ The scan descends one level, since C# groups attributes under an
+ ``attribute_list`` and Java annotations under ``modifiers``.
+ """
+ if not lmap.decorator_kinds:
+ return 0
+ region = fn_node
+ parent = fn_node.parent
+ if parent is not None and parent.type in lmap.decorated_definition_kinds:
+ region = parent
+ candidates: list[Node] = []
+ for child in region.children:
+ if child.type in lmap.block_kinds:
+ continue # the body, not the signature
+ candidates.append(child)
+ candidates.extend(child.children)
+ count = 0
+ for child in candidates:
+ if child.type not in lmap.decorator_kinds:
+ continue
+ if _contains_mock_call(child, lmap, dialect) or any(
+ token in name for name in _identifier_chain(child) for token in MOCK_IDENTIFIER_TOKENS
+ ):
+ count += 1
+ return count
+
+
+def _count_body_setup(body: Node, lmap: LanguageNodeMap, dialect: MockDialect) -> int:
+ """Mock-setup statements within *body*.
+
+ Statements are the named children of a block, so a nested block's
+ statements are counted once, at their own level.
+ """
+ count = 0
+
+ def _scan(block: Node) -> None:
+ nonlocal count
+ for stmt in block.children:
+ if not stmt.is_named:
+ continue
+ # Assertions are classified first and are never setup, even when
+ # they read a double (``mock.assert_called_once()``).
+ if _is_assertion_statement(stmt, lmap):
+ continue
+ if _is_config_assignment(stmt, lmap, dialect) or _contains_mock_call(
+ stmt, lmap, dialect
+ ):
+ count += 1
+
+ def _visit(node: Node) -> None:
+ if node.type in lmap.block_kinds:
+ _scan(node)
+ for child in node.children:
+ if child.type in lmap.function_kinds:
+ # Not collected as its own entry either, so its setup is
+ # dropped rather than reattributed. Only suppresses findings.
+ continue
+ _visit(child)
+
+ _visit(body)
+ return count
+
+
+def _count_mock_setup(
+ fn_node: Node,
+ body: Node,
+ lmap: LanguageNodeMap,
+ dialect: MockDialect | None,
+) -> int:
+ """Mock-setup statements for one function, decorators included."""
+ if dialect is None or not lmap.block_kinds or not lmap.call_kinds:
+ return 0
+ return _count_decorators(fn_node, lmap, dialect) + _count_body_setup(body, lmap, dialect)
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 942dac289..fb298ef77 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/models.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/models.py
@@ -49,6 +49,12 @@ class FunctionComplexity:
# ``LanguageNodeMap`` opts into assertion detection (``assert_kinds`` /
# ``assert_call_kinds``). Consumed by the test-quality biomarkers.
assertion_blocks: list[tuple[int, int, int]] = None # type: ignore[assignment]
+ # Every assertion statement in the body, runs or not. Same per-language
+ # opt-in as ``assertion_blocks``.
+ assertion_count: int = 0
+ # Mock-setup statements in the body, decorators included. 0 for a language
+ # with no entry in ``analysis/health/mocks/lexicon.py``.
+ mock_setup_count: int = 0
def __post_init__(self) -> None:
if self.complex_conditions is None:
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/walker.py b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
index c43adc058..0aaaf43bb 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
@@ -21,21 +21,23 @@ own ``FunctionComplexity`` row.
This module is the orchestrator: ``walk_file`` parses the source once and
drives the individual passes, each of which lives in its own sibling module:
-- ``models`` — the output dataclasses
-- ``ast_utils`` — name/text helpers, function-node collection, params
-- ``nloc`` — non-blank / non-comment line counting
-- ``cyclomatic`` — the CCN / cognitive / nesting engine
-- ``assertions`` — assertion-block detection (test-quality)
-- ``error_handling`` — error-handling anti-patterns
-- ``perf_walk`` — the performance-risk pass
-- ``class_analysis`` — class-level LCOM4 / god-class metrics
+- ``models``: the output dataclasses
+- ``ast_utils``: name/text helpers, function-node collection, params
+- ``nloc``: non-blank / non-comment line counting
+- ``cyclomatic``: the CCN / cognitive / nesting engine
+- ``assertions``: assertion blocks + per-function assertion totals
+- ``mock_walk``: per-function mock-setup counting (test-quality)
+- ``error_handling``: error-handling anti-patterns
+- ``perf_walk``: the performance-risk pass
+- ``class_analysis``: class-level LCOM4 / god-class metrics
"""
from __future__ import annotations
import structlog
-from .assertions import _collect_assertion_blocks
+from ..mocks.lexicon import mock_dialect as _mock_dialect
+from .assertions import _collect_assertion_facts
from .ast_utils import (
_collect_function_nodes,
_count_parameters,
@@ -45,6 +47,7 @@ from .class_analysis import _collect_classes
from .cyclomatic import _walk_function_body
from .error_handling import _collect_error_handling
from .languages import get_language_map
+from .mock_walk import _count_mock_setup, file_may_contain_mocks
# Re-exported so the package façade (``__init__``) and downstream consumers
# keep importing the output schema from ``complexity.walker`` unchanged.
@@ -129,9 +132,15 @@ def walk_file(
functions: list[FunctionComplexity] = []
fc_by_node_id: dict[int, FunctionComplexity] = {}
+ # Dialect first: it is a dict hit that rules out most languages before the
+ # byte scan. Keyed on language and bytes only, never the path, which is what
+ # the walk cache keys on.
+ dialect = _mock_dialect(language)
+ mock_dialect = dialect if dialect is not None and file_may_contain_mocks(source) else None
for fn_node in _collect_function_nodes(tree.root_node, lmap):
body = fn_node.child_by_field_name("body") or fn_node
ccn, max_nest, cognitive, bumps, conditions = _walk_function_body(body, lmap)
+ assertion_blocks, assertion_count = _collect_assertion_facts(body, lmap)
fc = FunctionComplexity(
name=_find_function_entry_name(fn_node, lmap),
start_line=fn_node.start_point[0] + 1,
@@ -143,7 +152,9 @@ def walk_file(
bumps=bumps,
param_count=_count_parameters(fn_node),
complex_conditions=conditions,
- assertion_blocks=_collect_assertion_blocks(body, lmap),
+ assertion_blocks=assertion_blocks,
+ assertion_count=assertion_count,
+ mock_setup_count=_count_mock_setup(fn_node, body, lmap, mock_dialect),
)
functions.append(fc)
fc_by_node_id[fn_node.id] = fc
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index 4dc048d93..37708e07f 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -99,10 +99,11 @@ log = structlog.get_logger(__name__)
# Not a licence to move a calibrated scoring weight — those are frozen
# independently of this stamp.
#
-# Current stamp: F# and Objective-C gained working complexity node maps and
-# Elixir lost its broken one, so stored complexity changes for files in those
-# languages. It has to move for the cache too: ``HealthWalkCache`` keys on this
-# stamp and the file's bytes, neither of which a node-map change alters.
+# Current stamp: ``mock_saturated_test`` landed and the walker records two new
+# ``FunctionComplexity`` fields, which a cached v11 walk does not carry.
+#
+# v11: F# and Objective-C gained working complexity node maps and Elixir lost
+# its broken one, so stored complexity changes for files in those languages.
#
# v10: non-code files stopped being scored and the deduction was split into its
# structure and history halves, stored per file.
@@ -121,7 +122,7 @@ log = structlog.get_logger(__name__)
# forms. Files that were counted untested and are not become tested, which
# moves untested-hotspot findings and the scores that carry them, on every
# language with a prefix or spec convention rather than Ruby alone.
-HEALTH_ANALYZER_VERSION = 11
+HEALTH_ANALYZER_VERSION = 12
# Method-level smells that make the dataflow / Extract Method pass worthwhile.
# Only files carrying one of these get a CFG + def/use + reaching pass built.
diff --git a/packages/core/src/repowise/core/analysis/health/mocks/__init__.py b/packages/core/src/repowise/core/analysis/health/mocks/__init__.py
new file mode 100644
index 000000000..7ca16e926
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/mocks/__init__.py
@@ -0,0 +1 @@
+"""Per-language mock vocabulary for the saturation pass. See ``lexicon.py``."""
diff --git a/packages/core/src/repowise/core/analysis/health/mocks/lexicon.py b/packages/core/src/repowise/core/analysis/health/mocks/lexicon.py
new file mode 100644
index 000000000..8b9f319d6
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/mocks/lexicon.py
@@ -0,0 +1,92 @@
+"""Per-language mock vocabulary, as data.
+
+The mock-saturation pass (``complexity/mock_walk.py``) is language-agnostic: every
+language difference lives in a :class:`MockDialect` row of :data:`MOCK_DIALECTS`.
+This mirrors the per-language plugin idiom used by ``perf/dialects/`` and
+``ingestion/resolvers/`` - one entry per language, registered in a dict, zero
+edits to the walker to add one - but the dialect is a frozen dataclass rather
+than a subclass, because every language difference here is vocabulary and none
+of it is behaviour. Adding a language is one row plus, if its grammar needs
+them, ``decorator_kinds`` / ``block_kinds`` on its ``LanguageNodeMap``.
+
+A language absent from ``MOCK_DIALECTS`` produces no mock signal at all, which
+is the safe default the precision-first house contract requires.
+
+The shared identifier tokens come from Hora and Robbes, "Are Coding Agents
+Generating Over-Mocked Tests? An Empirical Study", MSR '26
+(doi:10.1145/3793302.3793362), whose case-insensitive identifier match reached
+94% precision on 100 manually inspected commits. The taxonomy behind the token
+list is Meszaros, *xUnit Test Patterns* (2007). Their heuristic answers "does
+this commit introduce a mock?"; this pass asks the narrower question "is this
+statement mock setup?", so the guarded-token handling below is ours, not theirs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Test-double name tokens, matched case-insensitively as identifier
+# substrings. Shared rather than per-dialect: these are the names developers
+# give doubles in every language.
+MOCK_IDENTIFIER_TOKENS: frozenset[str] = frozenset(
+ {"dummy", "dummies", "stub", "mock", "mocks", "spy", "spies", "fake"}
+)
+
+
+@dataclass(frozen=True)
+class MockDialect:
+ """One language's mock vocabulary. Data only."""
+
+ #: Callee names that are mock setup whatever the receiver. Names carrying
+ #: a :data:`MOCK_IDENTIFIER_TOKENS` substring match on the token alone.
+ setup_callees: frozenset[str] = frozenset()
+
+ #: Names that mean mocking only in a mocking context: bare ``patch(...)``
+ #: and ``mock.patch(...)`` are doubles, ``client.patch("/url")`` is HTTP.
+ #: Counts with no receiver, or a receiver root in :attr:`guard_roots`.
+ guarded_callees: frozenset[str] = frozenset()
+
+ #: Receiver roots that license a :attr:`guarded_callees` match.
+ guard_roots: frozenset[str] = frozenset()
+
+ #: Receiver root -> the methods ON it that install a double, for fixtures
+ #: that mix doubling with other duties. A listed root matches on these
+ #: methods and nothing else.
+ receiver_methods: dict[str, frozenset[str]] = field(default_factory=dict)
+
+ #: Attributes whose assignment configures a double
+ #: (``client.get.return_value = ...``), where the receiver carries no token.
+ config_attributes: frozenset[str] = frozenset()
+
+ #: Test-case name prefixes, matched case-insensitively. Empty means the
+ #: language cannot tell from the name.
+ test_name_prefixes: tuple[str, ...] = field(default=())
+
+
+_PYTHON = MockDialect(
+ # ``unittest.mock`` members with no mock token in their names.
+ setup_callees=frozenset({"create_autospec", "seal"}),
+ guarded_callees=frozenset({"patch"}),
+ guard_roots=frozenset({"mock", "unittest"}),
+ # ``monkeypatch`` doubles only through the attribute and item setters;
+ # ``setenv`` / ``chdir`` arrange the process, which any test may do.
+ receiver_methods={
+ "monkeypatch": frozenset({"setattr", "delattr", "setitem", "delitem"}),
+ },
+ config_attributes=frozenset({"return_value", "side_effect"}),
+ test_name_prefixes=("test",),
+)
+
+
+# Keyed by ``LanguageTag`` (``ingestion/models.py``); one dialect may serve
+# several tags. Go stays out until it has an assertion vocabulary beyond
+# testify: its ``t.Error`` tests are invisible to the assert/expect prefix
+# match, which would make every ratio wrong.
+MOCK_DIALECTS: dict[str, MockDialect] = {
+ "python": _PYTHON,
+}
+
+
+def mock_dialect(language: str) -> MockDialect | None:
+ """The dialect for *language*, or ``None`` when it has no mock vocabulary."""
+ return MOCK_DIALECTS.get(language)
diff --git a/packages/core/src/repowise/core/analysis/health/models.py b/packages/core/src/repowise/core/analysis/health/models.py
index 6a1b7c897..2686fee1c 100644
--- a/packages/core/src/repowise/core/analysis/health/models.py
+++ b/packages/core/src/repowise/core/analysis/health/models.py
@@ -59,12 +59,19 @@ def primary_finding(findings: Sequence[Any]) -> Any | None:
``coverage_gradient``.
"""
from .biomarkers.registry import continuous_biomarkers
+ from .scoring import is_advisory
if not findings:
return None
+ # An advisory finding describes; it never accuses. Leaving it eligible made
+ # it the stated "one reason" for any file whose only open finding was
+ # advisory - printed beside a total deduction of zero.
+ candidates = [item for item in findings if not is_advisory(item.biomarker_type)]
+ if not candidates:
+ return None
continuous = continuous_biomarkers()
- discrete = [item for item in findings if item.biomarker_type not in continuous]
- return max(discrete or findings, key=lambda item: float(item.health_impact or 0.0))
+ discrete = [item for item in candidates if item.biomarker_type not in continuous]
+ return max(discrete or candidates, key=lambda item: float(item.health_impact or 0.0))
def split_by_origin(findings: Iterable[Any]) -> tuple[list[Any], list[Any]]:
diff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.py
index ecb7a88e8..e6d5a6484 100644
--- a/packages/core/src/repowise/core/analysis/health/scoring.py
+++ b/packages/core/src/repowise/core/analysis/health/scoring.py
@@ -179,6 +179,9 @@ _BIOMARKER_CATEGORY: dict[str, str] = {
"prior_defect": "organizational",
"large_assertion_block": "test_quality",
"duplicated_assertion_block": "test_quality",
+ # Never reaches a deduction; mapped so category-grouped surfaces do not
+ # file it under the ``size_and_complexity`` default.
+ "mock_saturated_test": "test_quality",
"error_handling": "error_handling",
# Governance biomarkers - written by the additive governance pass
"ungoverned_hotspot": "organizational",
@@ -203,6 +206,22 @@ _BIOMARKER_CATEGORY: dict[str, str] = {
DIMENSIONS: tuple[str, ...] = ("defect", "maintainability", "performance")
+# The one dimension that does not score. Deliberately NOT in ``DIMENSIONS``,
+# which is exactly the set ``score_file`` returns a number for: keeping it out
+# means there is no weight, category or cap table it can acquire. A marker homes
+# here when no defect corpus labels what it measures, so it can never be
+# calibrated. It still carries a severity, a reason and a home for display.
+ADVISORY_DIMENSION: str = "advisory"
+
+# Every dimension label a finding may carry, scored or not. Surfaces that filter
+# or display by dimension read this; scoring reads ``DIMENSIONS``.
+ALL_DIMENSIONS: tuple[str, ...] = (*DIMENSIONS, ADVISORY_DIMENSION)
+
+# Findings here carry a zero ``health_impact``, so they must stay out of
+# anything ranked or totalled by impact. ``performance`` deducts on its own
+# pillar only; ``advisory`` does not deduct at all.
+ZERO_IMPACT_DIMENSIONS: frozenset[str] = frozenset({"performance", ADVISORY_DIMENSION})
+
# Which dimensions each biomarker's deduction feeds. Biomarkers not listed here
# contribute to ``defect`` only - the historical behaviour, since every
# biomarker has always counted toward the single score. The maintainability
@@ -263,6 +282,9 @@ _BIOMARKER_DIMENSIONS: dict[str, set[str]] = {
"sql_select_star": {"maintainability"},
"sql_update_delete_without_where": {"maintainability"},
"sql_cartesian_join": {"performance"},
+ # Advisory. Must also appear in ``_ADVISORY_HOME``: the two tables are
+ # independent, and a marker in only one of them still deducts from defect.
+ "mock_saturated_test": {ADVISORY_DIMENSION},
}
# Maintainability per-biomarker weight multipliers. Expert-set by definition -
@@ -467,6 +489,10 @@ _PERFORMANCE_HOME: frozenset[str] = frozenset(
}
)
+# The display half of the pairing above; ``test_advisory_dimension.py`` locks
+# the two together for every registered biomarker.
+_ADVISORY_HOME: frozenset[str] = frozenset({"mock_saturated_test"})
+
def severity_deduction(sev: Severity) -> float:
return _SEVERITY_DEDUCTION.get(sev, 0.5)
@@ -495,6 +521,8 @@ def dimensions_for(name: str) -> set[str]:
def biomarker_dimension(name: str) -> str:
"""The finding's single 'home' dimension for display / per-pillar filtering."""
+ if name in _ADVISORY_HOME:
+ return ADVISORY_DIMENSION
if name in _PERFORMANCE_HOME:
return "performance"
if name in _MAINTAINABILITY_HOME:
@@ -502,6 +530,11 @@ def biomarker_dimension(name: str) -> str:
return "defect"
+def is_advisory(name: str) -> bool:
+ """True when *name* is a non-scoring marker (see ``ADVISORY_DIMENSION``)."""
+ return name in _ADVISORY_HOME
+
+
def maintainability_weight(name: str) -> float:
"""Maintainability multiplier; 1.0 for unknown biomarkers."""
return _MAINTAINABILITY_WEIGHT_MULTIPLIER.get(name, 1.0)
diff --git a/packages/core/src/repowise/core/analysis/review_directive.py b/packages/core/src/repowise/core/analysis/review_directive.py
index 99c0c3832..a46774b66 100644
--- a/packages/core/src/repowise/core/analysis/review_directive.py
+++ b/packages/core/src/repowise/core/analysis/review_directive.py
@@ -16,6 +16,7 @@ from dataclasses import dataclass
from typing import Literal
from .change_health.models import ChangeHealthDelta
+from .health.scoring import ADVISORY_DIMENSION
#: How much of a lane's evidence was actually computed.
#:
@@ -46,8 +47,9 @@ ReviewActionKind = Literal[
_BLOCKING_SEVERITIES = {"high", "critical"}
-#: Dimensions whose findings are advice, not a gate.
-_ADVISORY_DIMENSIONS = {"performance"}
+#: Dimensions whose findings are advice, not a gate. An unlisted dimension
+#: gates like a defect, which is the safe default.
+_ADVISORY_DIMENSIONS = {"performance", ADVISORY_DIMENSION}
#: Delta statuses that mean the comparison did not happen.
_NOT_COMPARED = {"unavailable", "unsupported_range", "too_large", "timeout"}
@@ -137,10 +139,13 @@ def _verdict(delta: ChangeHealthDelta) -> tuple[ReviewStatus, str, EvidenceState
f"starting with {lead.biomarker_type} in {lead.path}.",
state,
)
- if delta.findings:
+ # Performance is excluded from BLOCKING above but still counts here: it
+ # moves a score. Advisory never does.
+ scoring = [f for f in delta.findings if f.dimension != ADVISORY_DIMENSION]
+ if scoring:
return (
"review_recommended",
- f"{len(delta.findings)} new {_plural('finding', len(delta.findings))} "
+ f"{len(scoring)} new {_plural('finding', len(scoring))} "
"of low or advisory severity.",
state,
)
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 72cbe812c..04c7d8c1f 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health.py
@@ -27,7 +27,7 @@ from ....analysis.health.ranking import (
)
from ....analysis.health.rows import detail_map
from ....analysis.health.scope import scores_language
-from ....analysis.health.scoring import nloc_weighted_attr
+from ....analysis.health.scoring import ADVISORY_DIMENSION, nloc_weighted_attr
from ....test_paths import is_test_related_path
from ...models import (
GraphNode,
@@ -713,7 +713,9 @@ async def get_health_summary(
"average_health": round(avg, 2),
"worst_performer_path": worst.file_path,
"worst_performer_score": round(worst.score, 2),
- "open_findings": len(findings),
+ # Advisory findings carry a zero health impact, so counting them
+ # here would grow the headline without anything having got worse.
+ "open_findings": len(findings) - by_dim.get(ADVISORY_DIMENSION, 0),
"maintainability_average": _rounded(maintainability_average),
"performance_average": _rounded(performance_average),
# The headline's two halves, in deduction points. Both come off columns
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.py
index d9759728f..7978adb30 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py
@@ -37,7 +37,11 @@ from repowise.core.analysis.health.refactoring.recommendations import (
hydrate_recommendations,
)
from repowise.core.analysis.health.scope import DEFAULT_SCOPE, parse_scope
-from repowise.core.analysis.health.scoring import hotspot_health, nloc_weighted_attr
+from repowise.core.analysis.health.scoring import (
+ ALL_DIMENSIONS,
+ hotspot_health,
+ nloc_weighted_attr,
+)
from repowise.core.analysis.health.semantics import health_semantics_contract
from repowise.core.analysis.health.signals import file_signals
from repowise.core.analysis.health.suggestions import suggestion_for
@@ -1606,6 +1610,7 @@ async def get_health(
"performance",
"defect",
"maintainability",
+ "advisory",
}
unknown_include_keys = sorted(include_set - known_includes)
only_list = [_ONLY_ALIASES.get(k, k) for k in (only or [])]
@@ -1627,7 +1632,7 @@ async def get_health(
# ``include=["biomarkers", "performance"]`` filtered a defect-heavy head down
# to nothing while the total still reported the whole repo. The filter now
# decides which rows are eligible for the cap in the first place.
- dimension_filter = include_set & {"performance", "defect", "maintainability"}
+ dimension_filter = include_set & set(ALL_DIMENSIONS)
# The ranked findings list is ordered by health impact, and every
# performance finding carries zero impact by construction, so leaving it
# in an unfiltered list appends rows that can never rank and cannot be
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 5f14b81f3..ab8e4653d 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
@@ -9,6 +9,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.analysis.health.counts import parse_counts
from repowise.core.analysis.health.models import split_by_origin
from repowise.core.analysis.health.scope import parse_scope
+from repowise.core.analysis.health.scoring import ZERO_IMPACT_DIMENSIONS
from repowise.core.persistence import crud
from repowise.server.deps import get_db_session
from repowise.server.schemas import (
@@ -64,7 +65,7 @@ async def list_health_findings(
severity=severity,
dimension=dimension,
status=parse_status_filter(status),
- exclude_dimensions=("performance",),
+ exclude_dimensions=tuple(sorted(ZERO_IMPACT_DIMENSIONS)),
)
# A finding carries a path, not ``is_test``, so narrowing it needs the
# metric rows that do. Read them only when the answer depends on them:
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 cbc954fe5..657d26671 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
@@ -16,7 +16,7 @@ from repowise.core.analysis.health.defect_accuracy import compute_defect_accurac
from repowise.core.analysis.health.grading import band_for
from repowise.core.analysis.health.grading import distribution as health_distribution
from repowise.core.analysis.health.ranking import deduction_by_path
-from repowise.core.analysis.health.scoring import hotspot_health
+from repowise.core.analysis.health.scoring import ZERO_IMPACT_DIMENSIONS, hotspot_health
from repowise.core.persistence import crud
from repowise.server.deps import get_db_session
from repowise.server.mcp_server._meta import resolve_indexed_commit
@@ -124,12 +124,14 @@ async def health_overview(
deductions=deductions,
)
- # Ranked by health impact, so performance is out: its findings score zero
- # impact by construction and would fill the tail of a defect ranking with
- # rows the reader cannot compare against the ones above them. The counts
- # and breakdowns above still see every dimension; only this queue is
- # defect-and-maintainability work.
- ranked = [f for f in findings if (getattr(f, "dimension", None) or "defect") != "performance"]
+ # Ranked by health impact, so the zero-impact dimensions are out: they
+ # would fill the tail with rows a reader cannot compare against the ones
+ # above. The counts above still see every dimension.
+ ranked = [
+ f
+ for f in findings
+ if (getattr(f, "dimension", None) or "defect") not in ZERO_IMPACT_DIMENSIONS
+ ]
top_findings = await _attach_symbol_ids(
session, repo_id, [_finding_to_dict(f) for f in ranked[:limit]]
)
diff --git a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
index e6dd8c37f..4325372ab 100644
--- a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
+++ b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
@@ -12,6 +12,7 @@ from fastapi import Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.analysis.health.models import primary_finding
+from repowise.core.analysis.health.scoring import ZERO_IMPACT_DIMENSIONS
from repowise.core.analysis.health.suggestions import suggestion_for as _suggestion_for
from repowise.core.persistence import crud
from repowise.server.deps import get_db_session
@@ -107,7 +108,7 @@ async def health_work_queue(
# As the findings list does, so a row's count and the list behind it
# agree. Performance carries zero health impact and ranks by cause on
# its own surface; ``dimension=performance`` still returns it.
- exclude_dimensions=("performance",),
+ exclude_dimensions=tuple(sorted(ZERO_IMPACT_DIMENSIONS)),
)
metrics, findings = narrow(scope, metrics, findings)
metrics, findings, _unscored = project(counts, metrics, findings)
diff --git a/packages/types/src/health.ts b/packages/types/src/health.ts
index 7f62e9d27..672e960d6 100644
--- a/packages/types/src/health.ts
+++ b/packages/types/src/health.ts
@@ -39,15 +39,32 @@ export type HealthSeverity = "low" | "medium" | "high" | "critical";
* a parity test (`__tests__/health.test.ts` here,
* `tests/unit/health/test_scoring_dimensions.py` in core).
*/
-export type HealthDimension = "defect" | "maintainability" | "performance";
+export type ScoredHealthDimension = "defect" | "maintainability" | "performance";
-/** Canonical dimension order (parity-locked against core's `DIMENSIONS`). */
-export const HEALTH_DIMENSIONS: readonly HealthDimension[] = [
+/**
+ * The non-scoring fourth dimension. A marker homes here when it measures
+ * something no defect corpus labels, so it can never be calibrated and never
+ * earns weight. Its findings carry a zero health impact by construction and are
+ * kept out of every impact-ranked queue, so they describe without accusing.
+ *
+ * Mirror of `ADVISORY_DIMENSION` in core's `scoring.py`. Deliberately outside
+ * `HEALTH_DIMENSIONS`, which stays exactly the set that carries a score.
+ */
+export type AdvisoryHealthDimension = "advisory";
+
+/** Every dimension label a finding may carry on the wire, scored or not. */
+export type HealthDimension = ScoredHealthDimension | AdvisoryHealthDimension;
+
+/** Canonical SCORED dimension order (parity-locked against core's `DIMENSIONS`). */
+export const HEALTH_DIMENSIONS: readonly ScoredHealthDimension[] = [
"defect",
"maintainability",
"performance",
] as const;
+/** The dimension whose findings never move a number. */
+export const ADVISORY_DIMENSION: AdvisoryHealthDimension = "advisory";
+
/**
* What a code-health figure counts. `everything` is the calibrated score;
* `code_shape` removes the git-derived half, which rises as a file is worked
@@ -71,6 +88,7 @@ export const HEALTH_DIMENSION_LABEL: Record<HealthDimension, string> = {
defect: "Code health",
maintainability: "Maintainability",
performance: "Performance",
+ advisory: "Advisory",
};
/**
diff --git a/packages/ui/src/files/file-health-tab.tsx b/packages/ui/src/files/file-health-tab.tsx
index bd7864876..441cd70f0 100644
--- a/packages/ui/src/files/file-health-tab.tsx
+++ b/packages/ui/src/files/file-health-tab.tsx
@@ -10,7 +10,7 @@ import { BiomarkerDetails, type BiomarkerDetailsRecord } from "../health/biomark
import {
biomarkerInfo,
biomarkerLabel,
- biomarkerDimension,
+ asBiomarkerDimension,
CATEGORY_LABEL,
DIMENSION_LABEL,
type BiomarkerDimension,
@@ -375,12 +375,5 @@ export function FileHealthTab({
/** A finding's home pillar, preferring the server value over the glossary. */
function findingDimension(f: { dimension?: string; biomarker_type: string }): BiomarkerDimension {
- if (
- f.dimension === "defect" ||
- f.dimension === "maintainability" ||
- f.dimension === "performance"
- ) {
- return f.dimension;
- }
- return biomarkerDimension(f.biomarker_type);
+ return asBiomarkerDimension(f.dimension, f.biomarker_type);
}
diff --git a/packages/ui/src/health/biomarker-glossary.ts b/packages/ui/src/health/biomarker-glossary.ts
index 86cdc4e53..c9f89d229 100644
--- a/packages/ui/src/health/biomarker-glossary.ts
+++ b/packages/ui/src/health/biomarker-glossary.ts
@@ -202,6 +202,12 @@ export const BIOMARKER_GLOSSARY: Record<string, BiomarkerInfo> = {
description:
"A test function running a long unbroken run of assertions. When one fails, the rest never execute — split into focused cases.",
},
+ mock_saturated_test: {
+ label: "Mock saturated test",
+ category: "test_quality",
+ description:
+ "A test whose mock setup dwarfs what it checks, so it mostly verifies the collaboration the test itself wired up. Advisory: it costs this file no points.",
+ },
duplicated_assertion_block: {
label: "Duplicated assertions",
category: "test_quality",
@@ -354,7 +360,15 @@ export function biomarkerLabel(name: string): string {
* Health dimensions: which pillar a biomarker "homes" under
* ------------------------------------------------------------------ */
-export type BiomarkerDimension = "defect" | "maintainability" | "performance";
+export type BiomarkerDimension = "defect" | "maintainability" | "performance" | "advisory";
+
+/**
+ * Biomarkers that home to the non-scoring `advisory` dimension. They measure
+ * something real that no defect corpus labels, so they never deduct and the
+ * chip has to say so rather than borrowing the defect pillar's label. Mirror of
+ * ``_ADVISORY_HOME`` in core's `scoring.py`.
+ */
+export const ADVISORY_HOME_BIOMARKERS: ReadonlySet<string> = new Set(["mock_saturated_test"]);
/**
* The biomarkers whose "home" pillar is maintainability: the smells the defect
@@ -414,15 +428,37 @@ export const PERFORMANCE_HOME_BIOMARKERS: ReadonlySet<string> = new Set([
* only the biomarker type is known (e.g. a glossary entry).
*/
export function biomarkerDimension(name: string): BiomarkerDimension {
+ if (ADVISORY_HOME_BIOMARKERS.has(name)) return "advisory";
if (PERFORMANCE_HOME_BIOMARKERS.has(name)) return "performance";
if (MAINTAINABILITY_HOME_BIOMARKERS.has(name)) return "maintainability";
return "defect";
}
+/**
+ * A finding's home pillar, preferring the server's `dimension` over the
+ * glossary fallback. One owner on purpose: this narrowing was written out three
+ * times (the biomarker list, the file health tab, the file drawer) and every
+ * copy listed the dimensions by hand, so a fourth dimension would have rendered
+ * under the defect pillar's label in all three until each was found.
+ */
+export function asBiomarkerDimension(
+ dimension: string | null | undefined,
+ biomarkerType: string,
+): BiomarkerDimension {
+ // ``Object.hasOwn``, not a property probe: an indexed lookup reaches the
+ // prototype chain, so a server dimension of "constructor" or "toString" would
+ // pass and then render an undefined chip class.
+ if (dimension && Object.hasOwn(DIMENSION_LABEL, dimension)) {
+ return dimension as BiomarkerDimension;
+ }
+ return biomarkerDimension(biomarkerType);
+}
+
export const DIMENSION_LABEL: Record<BiomarkerDimension, string> = {
defect: "Code health",
maintainability: "Maintainability",
performance: "Performance",
+ advisory: "Advisory",
};
/** Tailwind chip classes per pillar, matching the surrounding chip palette. */
@@ -430,6 +466,9 @@ export const DIMENSION_CHIP: Record<BiomarkerDimension, string> = {
defect: "bg-[var(--color-accent-primary)]/10 text-[var(--color-accent-primary)]",
maintainability: "bg-[var(--color-accent-secondary)]/10 text-[var(--color-accent-secondary)]",
performance: "bg-[var(--color-info)]/10 text-[var(--color-info)]",
+ // Deliberately the most muted chip in the palette: an advisory finding costs
+ // the file nothing and must not read as urgent beside ones that do.
+ advisory: "bg-[var(--color-text-muted)]/10 text-[var(--color-text-muted)]",
};
/**
diff --git a/packages/ui/src/health/biomarker-list.tsx b/packages/ui/src/health/biomarker-list.tsx
index b7a66a227..8a85fe955 100644
--- a/packages/ui/src/health/biomarker-list.tsx
+++ b/packages/ui/src/health/biomarker-list.tsx
@@ -6,6 +6,7 @@ import { InfoTip } from "../shared/info-tip";
import {
biomarkerLabel,
biomarkerInfo,
+ asBiomarkerDimension,
biomarkerDimension,
CATEGORY_LABEL,
DIMENSION_CHIP,
@@ -41,14 +42,7 @@ export interface BiomarkerFinding {
/** A finding's home pillar, preferring the server value over the glossary. */
function findingDimension(f: BiomarkerFinding): BiomarkerDimension {
- if (
- f.dimension === "defect" ||
- f.dimension === "maintainability" ||
- f.dimension === "performance"
- ) {
- return f.dimension;
- }
- return biomarkerDimension(f.biomarker_type);
+ return asBiomarkerDimension(f.dimension, f.biomarker_type);
}
export interface BiomarkerListProps {
diff --git a/packages/ui/src/health/health-file-drawer.tsx b/packages/ui/src/health/health-file-drawer.tsx
index d25dbc8cd..72aaab24c 100644
--- a/packages/ui/src/health/health-file-drawer.tsx
+++ b/packages/ui/src/health/health-file-drawer.tsx
@@ -7,7 +7,7 @@ import { InfoTip } from "../shared/info-tip";
import {
biomarkerLabel,
biomarkerInfo,
- biomarkerDimension,
+ asBiomarkerDimension,
CATEGORY_CAP,
CATEGORY_LABEL,
DIMENSION_CHIP,
@@ -234,12 +234,7 @@ export function HealthFileDrawer({
</span>
);
}
- const dim =
- f.dimension === "maintainability" ||
- f.dimension === "defect" ||
- f.dimension === "performance"
- ? f.dimension
- : biomarkerDimension(f.biomarker_type);
+ const dim = asBiomarkerDimension(f.dimension, f.biomarker_type);
return (
<span
className={`inline-flex items-center rounded px-1.5 py-px text-[10px] font-medium ${DIMENSION_CHIP[dim]}`}
diff --git a/tests/unit/health/test_advisory_dimension.py b/tests/unit/health/test_advisory_dimension.py
new file mode 100644
index 000000000..e9d1ba002
--- /dev/null
+++ b/tests/unit/health/test_advisory_dimension.py
@@ -0,0 +1,238 @@
+"""The advisory dimension never moves a score, and cannot start to by accident.
+
+``HealthFindingData.dimension`` defaults to ``"defect"`` and ``dimensions_for``
+defaults to ``{"defect"}``, from two SEPARATE tables. A marker listed in only
+one of them displays as advisory while deducting from the defect score, and
+nothing caught that before these tests: the failure is silent, and it shows up
+as a defect regression on every repo at once.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.analysis.health.biomarkers.base import BiomarkerResult
+from repowise.core.analysis.health.biomarkers.registry import registered_biomarkers
+from repowise.core.analysis.health.models import HealthFindingData, Severity
+from repowise.core.analysis.health.scoring import (
+ ADVISORY_DIMENSION,
+ ALL_DIMENSIONS,
+ CATEGORY_CAPS,
+ DIMENSIONS,
+ attach_impacts,
+ biomarker_dimension,
+ dimensions_for,
+ is_advisory,
+ score_file,
+)
+
+_REGISTERED = [b.name for b in registered_biomarkers()]
+
+
+def _result(name: str, severity: Severity = Severity.HIGH) -> BiomarkerResult:
+ return BiomarkerResult(
+ biomarker_type=name,
+ severity=severity,
+ function_name="f",
+ line_start=1,
+ line_end=2,
+ details={},
+ )
+
+
+# ---------------------------------------------------------------------------
+# The dimension itself
+# ---------------------------------------------------------------------------
+
+
+def test_advisory_is_not_a_scored_dimension():
+ """``DIMENSIONS`` is the set that carries a score, and stays three."""
+ assert ADVISORY_DIMENSION not in DIMENSIONS
+ assert (*DIMENSIONS, ADVISORY_DIMENSION) == ALL_DIMENSIONS
+
+
+def test_score_file_returns_no_advisory_score():
+ """A dimension with no number cannot have one drift."""
+ scores, _ = score_file([_result("mock_saturated_test")])
+ assert ADVISORY_DIMENSION not in scores
+ assert set(scores) == set(DIMENSIONS)
+
+
+def test_advisory_has_no_weight_category_or_cap_table():
+ """Nothing is keyed on the advisory dimension in the scoring tables."""
+ assert ADVISORY_DIMENSION not in CATEGORY_CAPS
+
+
[email protected]("severity", list(Severity))
+def test_advisory_findings_never_deduct_at_any_severity(severity):
+ """Severity carries urgency for a reader; it must not reach a score."""
+ scores, deductions = score_file([_result("mock_saturated_test", severity)])
+ assert scores["defect"] == 10.0
+ assert scores["maintainability"] == 10.0
+ assert scores["performance"] == 10.0
+ assert deductions == [0.0]
+
+
+def test_advisory_findings_carry_zero_health_impact():
+ results = [_result("mock_saturated_test")]
+ _, deductions = score_file(results)
+ findings = attach_impacts(results, deductions)
+ assert findings[0].health_impact == 0.0
+ assert findings[0].dimension == ADVISORY_DIMENSION
+
+
+def test_advisory_findings_do_not_dilute_a_real_deduction():
+ """Adding an advisory finding to a scored one leaves the score alone."""
+ scored_only, _ = score_file([_result("brain_method")])
+ with_advisory, _ = score_file([_result("brain_method"), _result("mock_saturated_test")])
+ assert scored_only == with_advisory
+ assert with_advisory["defect"] < 10.0
+
+
+# ---------------------------------------------------------------------------
+# The trap: home and scoring membership are two tables that must agree
+# ---------------------------------------------------------------------------
+
+
[email protected]("name", _REGISTERED)
+def test_registered_biomarker_homes_where_it_scores(name):
+ """Every registered marker's home dimension is one it actually feeds.
+
+ This is the guard the default trap needs. ``biomarker_dimension`` (display)
+ and ``dimensions_for`` (scoring) are independent maps, so a marker added to
+ ``_ADVISORY_HOME`` alone keeps the ``{"defect"}`` default and deducts from
+ the surfaced score while claiming to be advisory - and a marker added to
+ ``_BIOMARKER_DIMENSIONS`` alone scores nothing while displaying as a defect.
+ """
+ assert biomarker_dimension(name) in dimensions_for(name), (
+ f"{name} homes to {biomarker_dimension(name)!r} but its deduction feeds "
+ f"{sorted(dimensions_for(name))}"
+ )
+
+
[email protected]("name", _REGISTERED)
+def test_advisory_markers_feed_no_scoring_dimension(name):
+ """An advisory marker is in the advisory dimension and nothing else."""
+ if not is_advisory(name):
+ return
+ assert dimensions_for(name) == {ADVISORY_DIMENSION}
+ assert not dimensions_for(name) & set(DIMENSIONS)
+
+
[email protected]("name", _REGISTERED)
+def test_scoring_markers_are_not_flagged_advisory(name):
+ """The predicate and the home label agree in both directions."""
+ assert is_advisory(name) is (biomarker_dimension(name) == ADVISORY_DIMENSION)
+
+
+def test_an_unregistered_biomarker_cannot_acquire_a_scoring_dimension_silently():
+ """An unknown id defaults into ``defect`` - so it must never be advisory.
+
+ The default is the whole trap: a marker someone forgot to register scores
+ as a defect. That is the safe direction (it is visible, not silent), but it
+ means "unknown" and "advisory" must never be the same answer, or a typo in
+ ``_ADVISORY_HOME`` would read as a working advisory marker.
+ """
+ unknown = "not_a_registered_biomarker_at_all"
+ assert dimensions_for(unknown) == {"defect"}
+ assert biomarker_dimension(unknown) == "defect"
+ assert not is_advisory(unknown)
+
+
+def test_every_advisory_home_entry_is_actually_registered():
+ """A name in ``_ADVISORY_HOME`` with no detector behind it is dead data."""
+ from repowise.core.analysis.health.scoring import _ADVISORY_HOME
+
+ assert set(_ADVISORY_HOME) <= set(_REGISTERED)
+
+
+# ---------------------------------------------------------------------------
+# Surfaces that must not read an advisory finding as a cost or a regression
+# ---------------------------------------------------------------------------
+
+
+def _finding(name: str, impact: float, dimension: str) -> HealthFindingData:
+ return HealthFindingData(
+ biomarker_type=name,
+ severity=Severity.MEDIUM,
+ file_path="tests/test_x.py",
+ function_name="test_x",
+ line_start=1,
+ line_end=2,
+ details={},
+ health_impact=impact,
+ dimension=dimension,
+ )
+
+
+def test_an_advisory_finding_is_never_a_files_dominant_cause():
+ """``primary_finding`` names the one reason a file is unhealthy.
+
+ A marker that costs the file nothing must not become the headline
+ accusation on a file whose only open finding is advisory.
+ """
+ from repowise.core.analysis.health.models import primary_finding
+
+ advisory = _finding("mock_saturated_test", 0.0, ADVISORY_DIMENSION)
+ assert primary_finding([advisory]) is None
+ scored = _finding("brain_method", 0.5, "defect")
+ assert primary_finding([advisory, scored]) is scored
+
+
+def test_score_breakdown_does_not_invent_a_deduction_for_an_advisory_finding():
+ """The breakdown explains where a file's points went.
+
+ Left in, an advisory finding contributes a raw deduction the file never
+ paid and trips ``capped`` on a category that was never capped.
+ """
+ from repowise.core.analysis.health.aggregation import score_breakdown
+
+ result = score_breakdown([_finding("mock_saturated_test", 0.0, ADVISORY_DIMENSION)])
+ assert result["categories"] == []
+ assert result["total_deduction"] == 0.0
+
+
+def test_severity_breakdown_excludes_advisory():
+ """It renders beside ``open_findings``, which also excludes advisory."""
+ from repowise.core.analysis.health.aggregation import severity_breakdown
+
+ counts = severity_breakdown(
+ [
+ _finding("mock_saturated_test", 0.0, ADVISORY_DIMENSION),
+ _finding("brain_method", 0.5, "defect"),
+ ]
+ )
+ assert counts["medium"] == 1
+
+
+def test_zero_impact_dimensions_is_the_one_owner():
+ """Three surfaces used to spell this set as their own literal."""
+ from repowise.core.analysis.health.scoring import ZERO_IMPACT_DIMENSIONS
+
+ assert ADVISORY_DIMENSION in ZERO_IMPACT_DIMENSIONS
+ assert "performance" in ZERO_IMPACT_DIMENSIONS
+ assert "defect" not in ZERO_IMPACT_DIMENSIONS
+
+
+def test_advisory_is_absent_from_every_change_delta_counter():
+ """Introduced, worsened, resolved AND unchanged.
+
+ The counters are derived from one match, so advisory is dropped from both
+ sides before matching rather than filtered per counter. ``unchanged_total``
+ is the one that made this worth doing: an advisory finding present on both
+ sides is not introduced, worsened or resolved, so every per-counter filter
+ missed it while it silently inflated the total beside them.
+ """
+ from repowise.core.analysis.change_health.matcher import FindingMatcher
+
+ advisory = _finding("mock_saturated_test", 0.0, ADVISORY_DIMENSION)
+ scored = _finding("brain_method", 0.5, "defect")
+ keep = [f for f in (advisory, scored) if not is_advisory(f.biomarker_type)]
+
+ both_sides = FindingMatcher({}).match([advisory, scored], [advisory, scored])
+ assert both_sides.unchanged_total == 2, "the matcher itself counts what it is given"
+
+ filtered = FindingMatcher({}).match(keep, keep)
+ assert filtered.unchanged_total == 1
+ assert filtered.resolved == []
+ assert filtered.of_kind("introduced", "worsened") == []
diff --git a/tests/unit/health/test_mock_saturated_test.py b/tests/unit/health/test_mock_saturated_test.py
new file mode 100644
index 000000000..e44560d3b
--- /dev/null
+++ b/tests/unit/health/test_mock_saturated_test.py
@@ -0,0 +1,431 @@
+"""``mock_saturated_test``: the mock-setup count, and the ratio it fires on.
+
+The counting cases are written as real source through the walker rather than as
+hand-built ``FunctionComplexity`` rows, because the failures worth catching here
+are grammar-shaped: a decorator that lives on the parent node, a receiver read
+in the wrong order, an HTTP ``patch`` that is not a mock.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.analysis.health.biomarkers.base import FileContext
+from repowise.core.analysis.health.biomarkers.mock_saturated_test import BIOMARKER
+from repowise.core.analysis.health.complexity import walk_file
+from repowise.core.analysis.health.complexity.mock_walk import file_may_contain_mocks
+from repowise.core.analysis.health.models import Severity
+
+
+def _walk(source: str) -> dict[str, tuple[int, int]]:
+ """``{function: (mock_setup_count, assertion_count)}`` for Python source."""
+ fc = walk_file("tests/test_sample.py", "python", source.encode("utf-8"))
+ return {f.name: (f.mock_setup_count, f.assertion_count) for f in fc.functions}
+
+
+def _detect(source: str, path: str = "tests/test_sample.py", language: str = "python"):
+ fc = walk_file(path, language, source.encode("utf-8"))
+ ctx = FileContext(
+ file_path=path,
+ language=language,
+ nloc=fc.file_nloc,
+ has_test_file=True,
+ module=None,
+ function_metrics={f.name: f for f in fc.functions},
+ )
+ return BIOMARKER.detect(ctx)
+
+
+# ---------------------------------------------------------------------------
+# Counting
+# ---------------------------------------------------------------------------
+
+
+def test_counts_constructors_config_and_decorators():
+ counts = _walk(
+ """
+from unittest.mock import MagicMock, patch
+
+@patch("pkg.mod.load")
+def test_saturated(mock_load):
+ client = MagicMock()
+ client.get.return_value = MagicMock()
+ repo = MagicMock()
+ repo.fetch.side_effect = [1, 2]
+ mock_load.return_value = repo
+ assert repo.fetch() == 1
+"""
+ )
+ # 1 decorator + 5 body statements; the assertion is not counted as setup.
+ assert counts["test_saturated"] == (6, 1)
+
+
+def test_a_statement_matching_twice_counts_once():
+ """``x.y.return_value = MagicMock()`` is one act of setup, not two."""
+ counts = _walk(
+ """
+from unittest.mock import MagicMock
+
+def test_one():
+ repo.load.return_value = MagicMock()
+ assert repo.load()
+"""
+ )
+ assert counts["test_one"] == (1, 1)
+
+
+def test_an_assertion_on_a_mock_is_not_setup():
+ """``mock.assert_called_once()`` reads the double but verifies with it.
+
+ It matches the mock vocabulary on its receiver, so without the
+ assertion-first rule it would count in both halves of the ratio.
+ """
+ counts = _walk(
+ """
+from unittest.mock import MagicMock
+
+def test_verifies():
+ client = MagicMock()
+ client.get()
+ client.get.assert_called_once()
+ client.post.assert_not_called()
+"""
+ )
+ mocks, asserts = counts["test_verifies"]
+ assert asserts == 2
+ assert mocks == 1 # only ``client = MagicMock()``
+
+
+def test_http_patch_is_not_a_mock():
+ """The context guard. ``client.patch("/url")`` is a PATCH request."""
+ counts = _walk(
+ """
+def test_http(client):
+ response = client.patch("/users/1", json={"a": 1})
+ other = client.patch("/users/2", json={"b": 2})
+ assert response.status_code == 200
+"""
+ )
+ assert counts["test_http"] == (0, 1)
+
+
+def test_bare_and_module_qualified_patch_are_mocks():
+ counts = _walk(
+ """
+import mock
+from unittest.mock import patch
+
+def test_bare():
+ with patch("pkg.a") as a:
+ assert a is not None
+
+def test_qualified():
+ with mock.patch("pkg.b") as b:
+ assert b is not None
+"""
+ )
+ assert counts["test_bare"][0] == 1
+ assert counts["test_qualified"][0] == 1
+
+
+def test_monkeypatch_counts_only_its_doubling_methods():
+ """Arranging the environment is not installing a test double."""
+ counts = _walk(
+ """
+def test_env(monkeypatch):
+ monkeypatch.setenv("A", "1")
+ monkeypatch.delenv("B", raising=False)
+ monkeypatch.chdir("/tmp")
+ monkeypatch.syspath_prepend("/x")
+ assert True
+
+def test_double(monkeypatch):
+ monkeypatch.setattr("pkg.a", 1)
+ monkeypatch.delattr("pkg.b")
+ monkeypatch.setitem({}, "k", 3)
+ assert True
+"""
+ )
+ assert counts["test_env"] == (0, 1)
+ assert counts["test_double"] == (3, 1)
+
+
+def test_nested_function_setup_does_not_count_against_its_parent():
+ """A closure's doubles belong to the closure, not the test around it.
+
+ The walker records no row for a function nested inside a function body, so
+ the setup is not attributed anywhere - which is the conservative direction:
+ it can only ever suppress a finding, never invent one.
+ """
+ counts = _walk(
+ """
+from unittest.mock import MagicMock
+
+def test_outer():
+ def helper():
+ a = MagicMock()
+ b = MagicMock()
+ return a, b
+
+ assert helper()
+"""
+ )
+ assert counts["test_outer"] == (0, 1)
+ assert "helper" not in counts
+
+
+def test_setup_inside_a_nested_block_is_counted():
+ counts = _walk(
+ """
+from unittest.mock import MagicMock
+
+def test_loop():
+ for _ in range(2):
+ client = MagicMock()
+ client.get.return_value = 1
+ assert client
+"""
+ )
+ assert counts["test_loop"] == (2, 1)
+
+
+# ---------------------------------------------------------------------------
+# The whole-file precheck
+# ---------------------------------------------------------------------------
+
+
+def test_precheck_skips_a_file_with_no_mock_vocabulary():
+ assert not file_may_contain_mocks(b"def f(x):\n return x + 1\n")
+
+
+ "source",
+ [b"MagicMock()", b"from unittest import mock", b"a_stub = 1", b"@patch('x')", b"SPY = 2"],
+)
+def test_precheck_is_case_insensitive_and_catches_the_vocabulary(source):
+ assert file_may_contain_mocks(source)
+
+
+def test_precheck_is_a_pure_function_of_the_bytes():
+ """It must not read the path: the walk cache keys on content and language."""
+ source = b"from unittest.mock import MagicMock\n"
+ assert file_may_contain_mocks(source) is file_may_contain_mocks(bytes(source))
+
+
+# ---------------------------------------------------------------------------
+# The detector
+# ---------------------------------------------------------------------------
+
+
+_SATURATED = """
+from unittest.mock import MagicMock
+
+def test_saturated():
+ a = MagicMock()
+ b = MagicMock()
+ c = MagicMock()
+ d = MagicMock()
+ e = MagicMock()
+ f = MagicMock()
+ a.go.return_value = b
+ assert a.go() is b
+"""
+
+
+def test_fires_on_a_saturated_test():
+ findings = _detect(_SATURATED)
+ assert [f.biomarker_type for f in findings] == ["mock_saturated_test"]
+ finding = findings[0]
+ assert finding.function_name == "test_saturated"
+ assert finding.details["mock_setup_count"] == 7
+ assert finding.details["assertion_count"] == 1
+ assert finding.details["ratio"] == 7.0
+
+
+def test_silent_on_a_production_file():
+ """Only test files. Production code that builds doubles is not a test."""
+ assert _detect(_SATURATED, path="src/pkg/module.py") == []
+
+
+def test_silent_when_assertions_keep_pace():
+ findings = _detect(
+ """
+from unittest.mock import MagicMock
+
+def test_balanced():
+ a = MagicMock()
+ b = MagicMock()
+ c = MagicMock()
+ d = MagicMock()
+ e = MagicMock()
+ f = MagicMock()
+ assert a
+ assert b
+ assert c
+ assert d
+"""
+ )
+ assert findings == []
+
+
+def test_silent_on_a_fixture_with_no_assertions():
+ """A mock factory with no assertions is correct code, not a saturated test.
+
+ It is also what ``assertion_free_test`` is for; firing here would report the
+ same function twice under two names.
+ """
+ findings = _detect(
+ """
+from unittest.mock import MagicMock
+
+def make_fake_repo():
+ repo = MagicMock()
+ repo.load.return_value = MagicMock()
+ repo.save.return_value = None
+ repo.drop.return_value = None
+ repo.list.return_value = []
+ repo.count.return_value = 0
+ return repo
+"""
+ )
+ assert findings == []
+
+
+def test_silent_below_the_absolute_setup_floor():
+ """Ratio alone is not enough: a small test is not saturated."""
+ findings = _detect(
+ """
+from unittest.mock import MagicMock
+
+def test_small():
+ a = MagicMock()
+ b = MagicMock()
+ c = MagicMock()
+ assert a
+"""
+ )
+ assert findings == []
+
+
+def test_silent_on_a_non_test_function_in_a_test_file():
+ findings = _detect(
+ """
+from unittest.mock import MagicMock
+
+def build_harness():
+ a = MagicMock()
+ b = MagicMock()
+ c = MagicMock()
+ d = MagicMock()
+ e = MagicMock()
+ f = MagicMock()
+ g = MagicMock()
+ assert a
+"""
+ )
+ assert findings == []
+
+
+def test_severity_rises_with_saturation():
+ low = _detect(_SATURATED)[0]
+ assert low.severity is Severity.LOW
+ high = _detect(
+ """
+from unittest.mock import MagicMock
+
+def test_very_saturated():
+ a = MagicMock()
+ b = MagicMock()
+ c = MagicMock()
+ d = MagicMock()
+ e = MagicMock()
+ f = MagicMock()
+ g = MagicMock()
+ h = MagicMock()
+ assert a
+"""
+ )[0]
+ assert high.severity is Severity.MEDIUM
+
+
+def test_a_language_with_no_dialect_produces_no_signal():
+ """Phase 1 is Python only; every other language must stay silent."""
+ findings = _detect(
+ """
+describe("thing", () => {
+ it("works", () => {
+ const a = jest.fn();
+ const b = jest.fn();
+ const c = jest.fn();
+ const d = jest.fn();
+ const e = jest.fn();
+ const f = jest.fn();
+ expect(a).toBeDefined();
+ });
+});
+""",
+ path="tests/thing.test.ts",
+ language="typescript",
+ )
+ assert findings == []
+
+
+# ---------------------------------------------------------------------------
+# Regressions found in review
+# ---------------------------------------------------------------------------
+
+
+def test_a_bare_local_named_return_value_is_not_mock_setup():
+ """A config attribute needs a receiver.
+
+ ``return_value = compute()`` is an ordinary local binding. Counting it
+ inflated the numerator on code that had no doubles in it at all.
+ """
+ counts = _walk(
+ """
+def test_local():
+ return_value = compute()
+ side_effect = other()
+ assert return_value
+ assert side_effect
+"""
+ )
+ assert counts["test_local"] == (0, 2)
+
+
+def test_an_argument_name_does_not_make_a_call_mock_ish():
+ """Only the callee names a call. ``check(mock_repo)`` is not mock setup."""
+ counts = _walk(
+ """
+def test_args(mock_repo):
+ check(mock_repo)
+ verify(mock_repo)
+ assert True
+"""
+ )
+ assert counts["test_args"][0] == 0
+
+
+def test_blocks_are_unchanged_by_the_assertion_total():
+ """The run scan is a calibrated, SCORING input and must not narrow.
+
+ Two assert-ish calls inside one assertion's argument list form a phantom
+ run of two. That is what ``duplicated_assertion_block`` was calibrated
+ against, so the total had to be scoped without touching the run scan.
+ """
+ counts = _walk(
+ """
+class T:
+ def test_nested_asserts(self):
+ self.assertEqual(assert_ok(a), assert_ok(b))
+"""
+ )
+ fc = walk_file(
+ "tests/test_sample.py",
+ "python",
+ b"class T:\n def test_nested_asserts(self):\n"
+ b" self.assertEqual(assert_ok(a), assert_ok(b))\n",
+ )
+ blocks = next(f.assertion_blocks for f in fc.functions if f.name == "test_nested_asserts")
+ assert blocks, "the phantom run must survive - duplicated_assertion_block reads it"
+ assert counts["test_nested_asserts"][1] == 1, "but the total counts one statement"
diff --git a/tests/unit/health/test_model_version_coupling.py b/tests/unit/health/test_model_version_coupling.py
index 83fb1f859..ede2d0e5e 100644
--- a/tests/unit/health/test_model_version_coupling.py
+++ b/tests/unit/health/test_model_version_coupling.py
@@ -22,7 +22,7 @@ from repowise.core.analysis.health.refactoring.identity import (
# The three stamps as they stand together. Moving either identity model means
# moving the analyzer with it, and updating this tuple in the same commit.
-_STAMPS = (11, 2, 2)
+_STAMPS = (12, 2, 2)
def test_the_identity_models_and_the_analyzer_stamp_are_pinned_together() -> None:
diff --git a/tests/unit/health/test_scoring_snapshot.py b/tests/unit/health/test_scoring_snapshot.py
index 5446c46aa..863377da3 100644
--- a/tests/unit/health/test_scoring_snapshot.py
+++ b/tests/unit/health/test_scoring_snapshot.py
@@ -111,6 +111,9 @@ _EXPECTED_BIOMARKER_CATEGORY = {
"prior_defect": "organizational",
"large_assertion_block": "test_quality",
"duplicated_assertion_block": "test_quality",
+ # Moves no score: its only dimension is ``advisory``, so ``score_file``
+ # filters it out before any category is summed.
+ "mock_saturated_test": "test_quality",
"error_handling": "error_handling",
# Phase 4B governance biomarkers.
"ungoverned_hotspot": "organizational",