Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.mdindex 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 ina 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-onlydiff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.pyindex 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 outdiff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.pyindex 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 FunctionComplexityfrom ..models import Severityfrom .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_nlocout.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 outdiff --git a/packages/core/src/repowise/core/analysis/health/complexity/markup.py b/packages/core/src/repowise/core/analysis/health/complexity/markup.pynew file mode 100644index 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.pyindex 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 = 0def __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.pyindex 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_sharefrom .file_scan import scan_filefrom .gating import is_gated_off, module_false_constantsfrom .languages import get_language_map+from .markup import markup_rows, rows_withinfrom .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.pyindex 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 genuinelarge_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_THRESHOLDassert 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.pynew file mode 100644index 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