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): size markers read judged CCN and code lines (#4116)

Raghav Chamadiya3902df095585
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 0e9082e99..e8a0bdd64 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -359,9 +359,13 @@ performance dimension a single `performance` category capped at 2.0. See §6.
`large_assertion_block` and `duplicated_assertion_block` are the two
**test-quality** smells (see §5.3). They fire only on test files and sit in
a deliberately small category so a noisy test can't dominate its own score.
-`large_method` is now gated on a minimal CCN floor (≥ 2) so a long-but-flat
-body (a big data literal) reads as layout, not a complexity smell: a small
-step toward decoupling the score from raw file size.
+`large_method` is gated on a minimal judged CCN (≥ 3) so a long-but-flat
+body (a big data literal, a dispatch of one-line arms) reads as layout, not a
+complexity smell. In `.tsx` / `.jsx` it counts code lines only: a line holding
+nothing but JSX tags, attributes or text is markup, while a line with a `{...}`
+expression is code. Its reason gives both measures, "N lines of code (M with
+blanks and comments)", and `details.span` carries M. `complex_method` reports
+the judged CCN that sets its severity and adds the raw CCN when they differ.
`ownership_risk` (long-run minor-contributor dispersion, Bird et al.) and
`churn_risk` (size-normalized relative churn, Nagappan-Ball) are git-only
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
index 8d0946d7b..45e969607 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
@@ -28,9 +28,15 @@ class ComplexMethodDetector:
def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
out: list[BiomarkerResult] = []
for fn in ctx.all_functions:
- severity = self.severity_for(judged_ccn(fn), fn.nloc)
+ judged = judged_ccn(fn)
+ severity = self.severity_for(judged, fn.nloc)
if severity is None:
continue
+ details = {"ccn": fn.ccn, "cognitive": fn.cognitive, "nloc": fn.nloc}
+ reason = f"{fn.name} has cyclomatic complexity {judged}"
+ if judged != fn.ccn:
+ details["judged_ccn"] = judged
+ reason += f" ({fn.ccn} counting every arm of its dispatch)"
out.append(
BiomarkerResult(
biomarker_type=self.name,
@@ -38,13 +44,8 @@ class ComplexMethodDetector:
function_name=fn.name,
line_start=fn.start_line,
line_end=fn.end_line,
- details={
- "ccn": fn.ccn,
- "cognitive": fn.cognitive,
- "nloc": fn.nloc,
- **shape_details(fn),
- },
- reason=f"{fn.name} has cyclomatic complexity {fn.ccn}",
+ details={**details, **shape_details(fn)},
+ reason=reason,
)
)
return out
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py
index f1ad86607..c49c1a88b 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py
@@ -1,36 +1,31 @@
"""Large Method — function bodies that exceed a healthy line budget.
-Fires on NLOC once a function carries *some* branching, so it measures
-length-with-substance rather than pure size. A long but perfectly flat
-body (a big config/data literal, a wall of sequential assignments — CCN 1)
-is a layout artefact, not a maintainability smell, and is excluded by the
-``_CCN_FLOOR`` gate. The complementary case — a short-but-tangled 60-line
-function with CCN 12 — is handled by ``complex_method``. Both can fire on
-the same function; the scorer caps the size_and_complexity category so
-they don't double-count.
+Counts lines of code, JSX markup lines excluded, once the judged CCN shows some
+branching: a long flat body (a data literal, a dispatch of one-line arms) is
+layout. ``complex_method`` covers short but tangled functions.
"""
from __future__ import annotations
+from ..complexity.dispatch import judged_ccn
+from ..complexity.models import FunctionComplexity
from ..models import Severity
from .base import BiomarkerResult, FileContext, shape_details
+def _reason(fn: FunctionComplexity, code_lines: int, span: int) -> str:
+ besides = f" besides {fn.markup_nloc} of JSX markup" if fn.markup_nloc else ""
+ return f"{fn.name} is {code_lines} lines of code{besides} ({span} with blanks and comments)"
+
+
class LargeMethodDetector:
name = "large_method"
category = "size_and_complexity"
_NLOC_THRESHOLD = 60
- # Minimal branching required so a long-but-flat body doesn't read as a
- # complexity smell. Set to 3 (not 2) so a flat ``match``/``case`` dispatch
- # table — every arm a single-expression return, functionally a data literal
- # — is excluded too: the walker gives it CCN 2 (base 1 + the lone ``match``
- # keyword point, no per-arm counting), the exact "layout artefact" shape
- # this floor exists to filter. Tradeoff: a long body whose *only* branch is
- # a single ``if``/``for`` also lands at CCN 2 and is now skipped. That is an
- # acceptable loss — a 60-line function with one branch is weak evidence of a
- # maintainability problem, and distinguishing it from a flat match would need
- # a per-function flat-match flag threaded from the walker (a larger change).
+ # 3, not 2: a flat ``match`` of single-expression arms scores CCN 2 (one point
+ # for the keyword), the layout artefact this floor filters. A long body with
+ # one ``if`` lands at 2 as well and is skipped, which is weak evidence anyway.
_CCN_FLOOR = 3
@classmethod
@@ -51,9 +46,17 @@ class LargeMethodDetector:
def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
out: list[BiomarkerResult] = []
for fn in ctx.all_functions:
- severity = self.severity_for(fn.ccn, fn.nloc)
+ code_lines = fn.nloc - fn.markup_nloc
+ judged = judged_ccn(fn)
+ severity = self.severity_for(judged, code_lines)
if severity is None:
continue
+ span = fn.end_line - fn.start_line + 1
+ details = {"nloc": fn.nloc, "ccn": fn.ccn, "span": span, **shape_details(fn)}
+ if judged != fn.ccn:
+ details["judged_ccn"] = judged
+ if fn.markup_nloc:
+ details["markup_nloc"] = fn.markup_nloc
out.append(
BiomarkerResult(
biomarker_type=self.name,
@@ -61,12 +64,8 @@ class LargeMethodDetector:
function_name=fn.name,
line_start=fn.start_line,
line_end=fn.end_line,
- details={
- "nloc": fn.nloc,
- "ccn": fn.ccn,
- **shape_details(fn),
- },
- reason=f"{fn.name} is {fn.nloc} lines long",
+ details=details,
+ reason=_reason(fn, code_lines, span),
)
)
return out
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/markup.py b/packages/core/src/repowise/core/analysis/health/complexity/markup.py
new file mode 100644
index 000000000..267f77f51
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/complexity/markup.py
@@ -0,0 +1,50 @@
+"""Lines of a JSX file that hold only markup: tags, attributes and text, no expression."""
+
+from __future__ import annotations
+
+from bisect import bisect_left, bisect_right
+from typing import TYPE_CHECKING
+
+from .nloc import _source_lines
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+#: Grammars that parse JSX; a ``.ts`` file reads with ``typescript`` and has none.
+_JSX_GRAMMARS = frozenset({"tsx", "javascript"})
+#: The ``{...}`` slot inside markup; what it holds is code again.
+_EXPRESSION_SLOT = "jsx_expression"
+
+
+def _token_rows(root: Node) -> tuple[set[int], set[int]]:
+ """Rows holding a markup token and rows holding a code token, comments skipped."""
+ markup: set[int] = set()
+ code: set[int] = set()
+ stack: list[tuple[Node, bool]] = [(root, False)]
+ while stack:
+ node, in_markup = stack.pop()
+ kind = node.type
+ if "comment" in kind:
+ continue
+ if kind.startswith("jsx_"):
+ in_markup = kind != _EXPRESSION_SLOT
+ if node.children:
+ stack.extend((child, in_markup) for child in node.children)
+ elif node.start_byte < node.end_byte:
+ rows = range(node.start_point[0], node.end_point[0] + 1)
+ (markup if in_markup else code).update(rows)
+ return markup, code
+
+
+def markup_rows(root: Node, grammar_tag: str, source: bytes) -> list[int]:
+ """Sorted 0-indexed non-blank rows whose every token is markup; ``[]`` without JSX."""
+ if grammar_tag not in _JSX_GRAMMARS or (b"/>" not in source and b"</" not in source):
+ return []
+ markup, code = _token_rows(root)
+ lines = _source_lines(source)
+ return sorted(row for row in markup - code if row < len(lines) and lines[row].strip())
+
+
+def rows_within(rows: list[int], node: Node) -> int:
+ """How many of the sorted *rows* fall inside *node*'s line span."""
+ return bisect_right(rows, node.end_point[0]) - bisect_left(rows, node.start_point[0])
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 482584cc3..248880ab4 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/models.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/models.py
@@ -142,6 +142,8 @@ class FunctionComplexity:
# function symbol by the health writer. ``dataflow.slice.function_facts``;
# None means not computed (a language with no map, or a failed read).
facts: FunctionFacts | None = None
+ # Of ``nloc``, the lines holding only JSX markup. ``complexity/markup.py``.
+ markup_nloc: 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 85f339d26..c754111ce 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
@@ -63,6 +63,7 @@ from .dispatch import dispatch_points, dispatch_share
from .file_scan import scan_file
from .gating import is_gated_off, module_false_constants
from .languages import get_language_map
+from .markup import markup_rows, rows_within
from .mock_walk import _count_mock_setup, file_may_contain_mocks
# Re-exported so the package façade (``__init__``) and downstream consumers
@@ -146,7 +147,8 @@ def walk_file(
# The grammar follows the path, the language tag does not: everything
# below still selects its dialects by ``language``. ``engine.py`` keys the
# walk cache on this same tag, so the two must not drift.
- grammar = _get_language(grammar_tag_for(language, abs_path))
+ grammar_tag = grammar_tag_for(language, abs_path)
+ grammar = _get_language(grammar_tag)
if grammar is None:
return FileComplexity(functions=[], classes=[], file_nloc=_count_file_nloc(source))
@@ -176,6 +178,7 @@ def walk_file(
asserts = _assert_dialect(language, extra_assert_names)
run_perf = perf_pass_runs(language, lmap)
scan = scan_file(tree.root_node, language, lmap, source, io_names=run_perf)
+ markup = markup_rows(tree.root_node, grammar_tag, source)
flags = module_false_constants(tree.root_node, source, language)
facts_of = _facts_reader(abs_path, language, lmap)
fn_nodes = _collect_function_nodes(tree.root_node, lmap)
@@ -214,6 +217,7 @@ def walk_file(
max_nesting=max_nest,
cognitive=cognitive,
nloc=scan.lines.count(body, source),
+ markup_nloc=rows_within(markup, body) if markup else 0,
bumps=bumps,
param_count=_count_parameters(fn_node),
typed_param_count=typed,
diff --git a/tests/unit/health/test_ff_track_iljk_structural.py b/tests/unit/health/test_ff_track_iljk_structural.py
index 43cb80348..e43d19406 100644
--- a/tests/unit/health/test_ff_track_iljk_structural.py
+++ b/tests/unit/health/test_ff_track_iljk_structural.py
@@ -51,11 +51,16 @@ def _god_class_src() -> str:
return "\n".join(lines) + "\n"
-def _flat_match_src() -> str:
- """A flat ``match``/``case`` dispatch table: every arm a single-expression
- return. Long enough to trip the NLOC threshold; CCN is 2 (base 1 + the lone
- match keyword point) — a layout artefact, not a complexity smell."""
- lines = ["def dispatch(status):", " match status:"]
+def _flat_match_src(tangled_arm: bool = False) -> str:
+ """A ``match``/``case`` dispatch table long enough to trip the NLOC threshold.
+
+ Every arm is a single-expression return unless *tangled_arm* nests branches in the first.
+ """
+ lines = ["def dispatch(status, flags):", " match status:"]
+ if tangled_arm:
+ lines += [" case -1:", " if flags.a:", " if flags.b:"]
+ lines += [" return 'ab'", " elif flags.c:"]
+ lines += [" return 'c'"]
for i in range(31):
lines.append(f" case {i}:")
lines.append(f' return "s{i}"')
@@ -67,10 +72,10 @@ def _flat_match_src() -> str:
def _branchy_src() -> str:
"""A long method with real branching (several ``if`` statements) — a genuine
large_method that must still fire after the CCN floor bump."""
- lines = ["def branchy(n):", " total = 0"]
- for i in range(5):
- lines.append(f" if n == {i}:")
- lines.append(f" total += {i}")
+ lines = ["def branchy(n, limit, step, seed):", " total = 0"]
+ for i, name in enumerate(("n", "total", "limit", "step", "seed")):
+ lines.append(f" if {name} > {i}:")
+ lines.append(f" total += {i}")
for i in range(60):
lines.append(f" total = total + {i}")
lines.append(" return total")
@@ -150,29 +155,22 @@ def test_unbounded_update_still_flagged(dialect):
# --------------------------------------------------------------------------
-# large_method: a large Python match dispatch is real branching (each case
-# is an if/elif-equivalent branch), so it is a size + complexity smell
+# large_method: a match dispatch is judged by the CCN around it plus its
+# heaviest arm, so a table of one-line arms is layout and a tangled arm is not
# --------------------------------------------------------------------------
-def test_large_method_fires_on_match_dispatch():
- """A 31-case Python ``match`` dispatch is real branching, not layout.
-
- Regression for #1774: Python match/case is pattern matching — each case
- is a distinct branch, structurally an if/elif chain. The old flat-match
- suppression reported this dispatch at CCN 2, which let a 65-line
- dispatcher dodge the large-method detector. It now counts each arm and
- must be flagged like any other tangled large method.
- """
- fm = walk_file("m.py", "python", _flat_match_src().encode())
- assert fm.functions, "expected a function to be parsed"
- fn = fm.functions[0]
- # Trips the NLOC threshold and now also the CCN floor (31 arms + base).
+def test_large_method_skips_a_match_dispatch_of_one_line_arms():
+ fn = walk_file("m.py", "python", _flat_match_src().encode()).functions[0]
assert fn.nloc >= LargeMethodDetector._NLOC_THRESHOLD
assert fn.ccn >= LargeMethodDetector._CCN_FLOOR
+ assert LargeMethodDetector().detect(_fn_ctx([fn])) == []
+
+
+def test_large_method_fires_on_a_match_dispatch_with_a_tangled_arm():
+ fn = walk_file("m.py", "python", _flat_match_src(tangled_arm=True).encode()).functions[0]
out = LargeMethodDetector().detect(_fn_ctx([fn]))
- assert len(out) == 1, "a large match dispatch must be flagged as large"
- assert out[0].function_name == "dispatch"
+ assert [f.function_name for f in out] == ["dispatch"]
def test_large_method_still_fires_on_real_branching():
diff --git a/tests/unit/health/test_method_size_accuracy.py b/tests/unit/health/test_method_size_accuracy.py
new file mode 100644
index 000000000..f5d7df759
--- /dev/null
+++ b/tests/unit/health/test_method_size_accuracy.py
@@ -0,0 +1,88 @@
+"""large_method and complex_method read the CCN that drives severity and count code, not markup."""
+
+from __future__ import annotations
+
+from repowise.core.analysis.health.biomarkers import FileContext
+from repowise.core.analysis.health.biomarkers.complex_method import ComplexMethodDetector
+from repowise.core.analysis.health.biomarkers.large_method import LargeMethodDetector
+from repowise.core.analysis.health.complexity.models import FunctionComplexity
+from repowise.core.analysis.health.complexity.walker import walk_file
+
+
+def _ctx(*functions: FunctionComplexity, path: str = "src/mod.py") -> FileContext:
+ return FileContext(
+ file_path=path, language="python", nloc=200, has_test_file=False, module=None,
+ all_functions=tuple(functions),
+ )
+
+
+def _fn(**kw) -> FunctionComplexity:
+ base = {"name": "tokenize", "start_line": 10, "end_line": 109, "ccn": 4,
+ "max_nesting": 1, "cognitive": 3, "nloc": 80}
+ return FunctionComplexity(**{**base, **kw})
+
+
+def test_large_method_skips_a_long_dispatch_whose_judged_ccn_is_flat() -> None:
+ # Raw CCN 10, all of it one dispatch of one-line arms: judged CCN 1.
+ dispatch = _fn(ccn=10, dispatch_share=1.0, dispatch_arm=0)
+ assert LargeMethodDetector().detect(_ctx(dispatch)) == []
+
+
+def test_large_method_reason_separates_code_lines_from_the_span() -> None:
+ [finding] = LargeMethodDetector().detect(_ctx(_fn()))
+ assert finding.reason == "tokenize is 80 lines of code (100 with blanks and comments)"
+ assert finding.details["span"] == 100
+
+
+def test_complex_method_prints_the_judged_ccn_beside_the_raw_one() -> None:
+ # 30 - round(0.6 * 29) + 2 = 15: severity HIGH comes from the judged value.
+ fn = _fn(ccn=30, dispatch_share=0.6, dispatch_arm=2)
+ [finding] = ComplexMethodDetector().detect(_ctx(fn))
+ assert finding.severity == "high"
+ assert finding.reason == (
+ "tokenize has cyclomatic complexity 15 (30 counting every arm of its dispatch)"
+ )
+ assert finding.details["ccn"] == 30
+ assert finding.details["judged_ccn"] == 15
+
+
+def test_complex_method_reason_is_unchanged_without_a_dominant_dispatch() -> None:
+ [finding] = ComplexMethodDetector().detect(_ctx(_fn(ccn=12)))
+ assert finding.reason == "tokenize has cyclomatic complexity 12"
+ assert "judged_ccn" not in finding.details
+
+
+_ROWS = "\n".join(
+ f' <li className="row-{i}">\n <span>Row {i}</span>\n </li>'
+ for i in range(25)
+)
+_COMPONENT = f"""export function Panel({{ items, open }}: Props) {{
+ if (!open) {{
+ return null;
+ }}
+ const label = items.length > 0 ? "Items" : "Empty";
+ return (
+ <section className="panel">
+ <h2>{{label}}</h2>
+ <ul>
+{_ROWS}
+ </ul>
+ </section>
+ );
+}}
+"""
+
+
+def test_large_method_does_not_count_jsx_markup_lines() -> None:
+ fcx = walk_file("src/Panel.tsx", "typescript", _COMPONENT.encode())
+ [panel] = [fn for fn in fcx.functions if fn.name == "Panel"]
+ assert panel.nloc >= 80
+ assert panel.markup_nloc >= 75
+ assert LargeMethodDetector().detect(_ctx(panel, path="src/Panel.tsx")) == []
+
+
+def test_logic_lines_inside_jsx_still_count_as_code() -> None:
+ fcx = walk_file("src/Panel.tsx", "typescript", _COMPONENT.encode())
+ [panel] = [fn for fn in fcx.functions if fn.name == "Panel"]
+ # ``<h2>{label}</h2>`` holds an expression, so it is code.
+ assert panel.nloc - panel.markup_nloc >= 6