codecoco 3.5.1__py3-none-any.whl

cognitive_complexity/discovery.py

@@ -0,0 +1,193 @@
+"""Function discovery and scoring: path walking, AST traversal, qualname construction.
+
+Library-level entry points for enumerating and scoring Python functions from
+files and directories, without the CLI presentation layer.
+"""
+
+from __future__ import annotations
+
+import ast
+import io
+import sys
+import tokenize
+from collections.abc import Iterator
+from pathlib import Path
+
+from cognitive_complexity.api import get_cognitive_complexity_breakdown
+from cognitive_complexity.common_types import AnyFuncdef, ScoredFunction, SkippedFile, is_funcdef
+
+_IGNORE_DIRECTIVE = "cococo: ignore"
+
+
+def iter_python_files(paths: list[str]) -> Iterator[Path]:
+    for raw in paths:
+        path = Path(raw)
+        if path.is_dir():
+            yield from sorted(path.rglob("*.py"))
+        elif path.suffix == ".py":
+            yield path
+
+
+def _collect(
+    node: ast.AST,
+    qualifier: str,
+    out: list[tuple[AnyFuncdef, str]],
+    fold_nested: bool = False,
+) -> None:
+    """Discover the functions to score under ``node``.
+
+    ``qualifier`` is the enclosing-name prefix threaded down the recursion: a
+    class extends it with ``Klass.`` and a named def extends it with
+    ``name.<locals>.`` before recursing, so nested defs report as
+    ``outer.<locals>.inner`` and method-local defs keep the class
+    (``Klass.method.<locals>.inner``). By default nested functions are their own
+    units (the recursion descends into them). In fold mode (pre-2.0.0 compat)
+    nested defs are *not* listed separately — they fold into the enclosing
+    function's score — so the recursion does not descend into them.
+    """
+    for child in ast.iter_child_nodes(node):
+        if is_funcdef(child):
+            qualname = f"{qualifier}{child.name}"
+            out.append((child, qualname))
+            if not fold_nested:
+                _collect(child, f"{qualname}.<locals>.", out, fold_nested)
+        elif isinstance(child, ast.ClassDef):
+            _collect(child, f"{qualifier}{child.name}.", out, fold_nested)
+        else:
+            _collect(child, qualifier, out, fold_nested)
+
+
+def scan(
+    paths: list[str], fold_nested: bool = False
+) -> tuple[list[ScoredFunction], list[SkippedFile], int]:
+    """Score every function under ``paths``; also return skipped files and scan count.
+
+    A file that cannot be read, parsed, or scored is reported on stderr and
+    recorded as skipped — never silently dropped — so the caller can fail a
+    ``--max`` gate and the JSON report can expose coverage, rather than launder a
+    partial scan as clean. ``files_scanned`` counts the files that parsed.
+    """
+    files = list(iter_python_files(paths))
+    outcomes = [_score_or_skip(path, fold_nested) for path in files]
+    results = [func for scored, _ in outcomes for func in scored]
+    skipped = [info for _, info in outcomes if info is not None]
+    return results, skipped, len(files) - len(skipped)
+
+
+def _score_or_skip(
+    path: Path, fold_nested: bool
+) -> tuple[list[ScoredFunction], SkippedFile | None]:
+    """Score one file, or report+record it as skipped on any unscoreable failure.
+
+    Returns ``(scored, None)`` on success or ``([], SkippedFile)`` on failure.
+    Catches read/parse errors and ``RecursionError`` from a pathologically deep
+    AST (a crafted subscript chain, a huge ``elif`` ladder) so one bad file is
+    skipped loudly rather than aborting the whole run.
+    """
+    try:
+        return _score_file(path, fold_nested), None
+    except (OSError, UnicodeDecodeError, SyntaxError, RecursionError) as exc:
+        reason = f"{type(exc).__name__}: {exc}"
+        print(f"cococo: skipped {path}: {reason}", file=sys.stderr)
+        return [], SkippedFile(path, reason)
+
+
+def _parse_file(path: Path) -> tuple[str, ast.Module]:
+    """Read ``path`` as UTF-8 and parse it, returning ``(source, tree)``.
+
+    The single read+parse site shared by the scanner and ``--explain``; it raises
+    ``OSError`` / ``UnicodeDecodeError`` / ``SyntaxError`` for the caller to map
+    to a skip or a clean message — one policy, not three drifting copies. The
+    source text comes back too so the scanner can read ``# cococo: ignore``
+    directives (comments are not in the AST).
+    """
+    source = path.read_text(encoding="utf-8")
+    return source, ast.parse(source, filename=str(path))
+
+
+def _ignored_lines(source: str) -> set[int]:
+    """Line numbers carrying a ``# cococo: ignore`` comment.
+
+    ``source`` has already parsed cleanly (the caller parsed it first), so
+    tokenizing it raises nothing; only real comment tokens are matched, so the
+    directive text appearing inside a string literal does not count.
+    """
+    return {
+        tok.start[0]
+        for tok in tokenize.generate_tokens(io.StringIO(source).readline)
+        if tok.type == tokenize.COMMENT and _IGNORE_DIRECTIVE in tok.string
+    }
+
+
+def _score_file(path: Path, fold_nested: bool) -> list[ScoredFunction]:
+    """Parse and score every function in one file (raises on read/parse/score failure)."""
+    source, tree = _parse_file(path)
+    ignore = _ignored_lines(source)
+    funcs: list[tuple[AnyFuncdef, str]] = []
+    _collect(tree, "", funcs, fold_nested)
+    return [_score_one(funcdef, qualname, path, fold_nested, ignore) for funcdef, qualname in funcs]
+
+
+def _score_one(
+    funcdef: AnyFuncdef, qualname: str, path: Path, fold_nested: bool, ignore: set[int]
+) -> ScoredFunction:
+    # Compute the breakdown once and carry it on the result; the JSON report and
+    # gate-suggestion paths read ``.breakdown`` instead of re-walking the tree
+    # (the scalar score is just its points sum).
+    breakdown = get_cognitive_complexity_breakdown(funcdef, fold_nested)
+    score = sum(c.points for c in breakdown)
+    return ScoredFunction(
+        score, path, funcdef.lineno, qualname, funcdef, breakdown, funcdef.lineno in ignore
+    )
+
+
+def scored_functions(paths: list[str], fold_nested: bool = False) -> list[ScoredFunction]:
+    """Score every function found under ``paths``, keeping its AST node."""
+    return scan(paths, fold_nested)[0]
+
+
+def parse_target(target: str) -> tuple[Path, str | None, int | None]:
+    """Split ``file.py::qualname`` / ``file.py:lineno`` / ``file.py`` into parts.
+
+    Returns ``(path, qualname, lineno)`` with exactly one of qualname/lineno set
+    (or both ``None`` to mean "the only function in the file").
+    """
+    if "::" in target:
+        raw, _, qual = target.partition("::")
+        return Path(raw), qual, None
+    head, sep, tail = target.rpartition(":")
+    if sep and tail.isdigit() and head.endswith(".py"):
+        return Path(head), None, int(tail)
+    return Path(target), None, None
+
+
+def find_function(
+    path: Path,
+    qualname: str | None,
+    lineno: int | None,
+    fold_nested: bool = False,
+) -> tuple[AnyFuncdef, str]:
+    """Locate one function in ``path`` by qualname or line number.
+
+    With neither selector, the file must contain exactly one function.
+    """
+    _, tree = _parse_file(path)
+    funcs: list[tuple[AnyFuncdef, str]] = []
+    _collect(tree, "", funcs, fold_nested)
+    if not funcs:
+        raise LookupError(f"no functions found in {path}")
+    if qualname is not None:
+        matches = [f for f in funcs if f[1] == qualname]
+        if not matches:
+            known = ", ".join(sorted(q for _, q in funcs))
+            raise LookupError(f"no function {qualname!r} in {path}; found: {known}")
+        return matches[0]
+    if lineno is not None:
+        matches = [f for f in funcs if f[0].lineno == lineno]
+        if not matches:
+            raise LookupError(f"no function defined on line {lineno} of {path}")
+        return matches[0]
+    if len(funcs) != 1:
+        known = ", ".join(sorted(q for _, q in funcs))
+        raise LookupError(f"{path} has {len(funcs)} functions; name one (file.py::qual): {known}")
+    return funcs[0]

cognitive_complexity/refactor.py

@@ -0,0 +1,388 @@
+"""Heuristic refactor suggestions derived from the complexity breakdown.
+
+Clean-room: the region model, thresholds, and reduction estimates here are our
+own. Each suggestion reads the same per-construct :class:`Contribution` data the
+scorer emits, so its estimated drop stays consistent with the reported score,
+and names one concrete, mechanical refactor. Designed to be actionable for a
+human or an agent reading a failing ``--max`` gate.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import NamedTuple
+
+from cognitive_complexity.api import Contribution
+from cognitive_complexity.common_types import AnyFuncdef, is_funcdef
+
+# Heuristic thresholds (ours, not part of Campbell's metric). Tuned to surface
+# only refactors that meaningfully cut the score; adjust here, in one place.
+_MIN_REDUCTION = 2  # ignore suggestions that barely move the score
+_MAX_SUGGESTIONS = 3  # keep the report focused on the biggest wins
+_EXTRACT_MIN_POINTS = 6  # a block heavy enough to pull into its own helper
+_EXTRACT_MIN_LINES = 5
+_MAX_COUPLING = 4  # max number of variables crossing the boundary before extraction is harmful
+_DISPATCH_MIN_ARMS = 3  # elif arms before "split into a dispatch table"
+_DISPATCH_MIN_CASES = 4  # match cases, ditto
+_PREDICATE_MIN_POINTS = 2  # a boolean expression worth naming
+
+_REGION_TYPES = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.Try,
+    ast.With,
+    ast.AsyncWith,
+    ast.Match,
+)
+
+_STEPS: dict[str, tuple[str, ...]] = {
+    "guard_clause": (
+        "Invert the condition and return/continue early when it fails.",
+        "De-indent the main path one level.",
+        "Repeat for any further nested guards.",
+    ),
+    "extract_helper": (
+        "Move this block into a small named helper.",
+        "Pass the values it reads as parameters.",
+        "Return what the caller needs.",
+    ),
+    "split_dispatcher": (
+        "Map each case to a named handler function.",
+        "Replace the chain with a dispatch dict (or a thin delegating match).",
+        "Keep this function a shallow orchestrator.",
+    ),
+    "extract_predicate": (
+        "Move this boolean expression into a well-named predicate function.",
+        "Call the predicate in the condition.",
+        "Keep the control flow here focused on branching.",
+    ),
+}
+
+_TITLES: dict[str, str] = {
+    "guard_clause": "Flatten nested block with a guard clause",
+    "extract_helper": "Extract this block into a helper function",
+    "split_dispatcher": "Replace the branch ladder with a dispatch table",
+    "extract_predicate": "Name this complex condition as a predicate",
+}
+
+
+class Suggestion(NamedTuple):
+    """One concrete, mechanical refactor for a too-complex function.
+
+    ``estimated_reduction`` is how many points the score should drop if applied;
+    ``estimated_complexity_after`` is the function total minus that. ``kind`` is a
+    stable machine id (see :data:`_TITLES`); ``autofixable`` flags the kinds the
+    ``--fix`` rewriter can apply on its own.
+    """
+
+    kind: str
+    title: str
+    line_start: int
+    line_end: int
+    estimated_reduction: int
+    estimated_complexity_after: int
+    autofixable: bool
+    steps: tuple[str, ...]
+
+
+def suggest_refactors(funcdef: AnyFuncdef, breakdown: list[Contribution]) -> list[Suggestion]:
+    """Up to a few high-value refactors for ``funcdef``, biggest reduction first."""
+    total = sum(c.points for c in breakdown)
+    candidates: list[Suggestion] = []
+    candidates += _guard_suggestions(funcdef, breakdown, total)
+    candidates += _predicate_suggestions(funcdef, breakdown, total)
+    for region in _iter_regions(funcdef):
+        candidates += _region_suggestions(funcdef, region, breakdown, total)
+    return _select(candidates)
+
+
+def _make(kind: str, start: int, end: int, reduction: int, total: int) -> Suggestion:
+    return Suggestion(
+        kind=kind,
+        title=_TITLES[kind],
+        line_start=start,
+        line_end=end,
+        estimated_reduction=reduction,
+        estimated_complexity_after=max(0, total - reduction),
+        autofixable=kind == "guard_clause",
+        steps=_STEPS[kind],
+    )
+
+
+def _iter_regions(node: ast.AST) -> list[ast.stmt]:
+    """Control-flow regions in the function, not descending into nested defs.
+
+    Nested ``def``/``async def`` are independent units, so their inner control
+    flow is left out of this function's region list.
+    """
+    regions: list[ast.stmt] = []
+    for child in ast.iter_child_nodes(node):
+        if is_funcdef(child):
+            continue
+        if isinstance(child, _REGION_TYPES):
+            regions.append(child)
+        regions.extend(_iter_regions(child))
+    return regions
+
+
+def _subtree_points(breakdown: list[Contribution], start: int, end: int) -> int:
+    return sum(c.points for c in breakdown if start <= c.lineno <= end)
+
+
+def _guard_suggestions(
+    funcdef: AnyFuncdef, breakdown: list[Contribution], total: int
+) -> list[Suggestion]:
+    out: list[Suggestion] = []
+    for node in _iter_regions(funcdef):
+        if not isinstance(node, ast.If) or node.orelse or not node.body:
+            continue
+        body_start = node.body[0].lineno
+        end = node.end_lineno or body_start
+        saved = sum(
+            1
+            for c in breakdown
+            if body_start <= c.lineno <= end and c.nesting_counted and c.lineno != node.lineno
+        )
+        if saved:
+            out.append(_make("guard_clause", node.lineno, end, saved, total))
+    return out
+
+
+def _region_suggestions(
+    funcdef: AnyFuncdef, region: ast.stmt, breakdown: list[Contribution], total: int
+) -> list[Suggestion]:
+    start = region.lineno
+    end = region.end_lineno or start
+    out: list[Suggestion] = []
+    points = _subtree_points(breakdown, start, end)
+    # ``points < total`` keeps us from advising "extract the whole function" when
+    # one region spans the entire body; that region carries every point.
+    big_enough = points >= _EXTRACT_MIN_POINTS and (end - start + 1) >= _EXTRACT_MIN_LINES
+    if (
+        big_enough
+        and points < total
+        and _is_extractable_region(region)
+        and _analyze_coupling(funcdef, region) <= _MAX_COUPLING
+    ):
+        out.append(_make("extract_helper", start, end, points, total))
+    dispatch = _dispatch_reduction(region)
+    if dispatch:
+        out.append(_make("split_dispatcher", start, end, dispatch, total))
+    return out
+
+
+def _is_extractable_region(region: ast.stmt) -> bool:
+    """Whether a region is a reasonable candidate for a plain helper extraction."""
+    if any(
+        isinstance(node, (ast.Break, ast.Continue, ast.Return, ast.Yield, ast.YieldFrom))
+        for node in ast.walk(region)
+    ):
+        return False
+    return _attribute_mutation_count(region) <= _MAX_COUPLING
+
+
+def _attribute_mutation_count(region: ast.stmt) -> int:
+    attrs: set[str] = set()
+    for node in ast.walk(region):
+        for target in _mutation_targets(node):
+            attrs.update(_stored_attribute_keys(target))
+    return len(attrs)
+
+
+def _mutation_targets(node: ast.AST) -> list[ast.AST]:
+    if isinstance(node, ast.Assign):
+        return list(node.targets)
+    if isinstance(node, ast.AnnAssign | ast.AugAssign | ast.NamedExpr):
+        return [node.target]
+    return []
+
+
+def _stored_attribute_keys(node: ast.AST) -> set[str]:
+    if isinstance(node, ast.Attribute):
+        return {ast.unparse(node)}
+    if isinstance(node, ast.Tuple | ast.List):
+        return {key for item in node.elts for key in _stored_attribute_keys(item)}
+    return set()
+
+
+def _analyze_coupling(funcdef: AnyFuncdef, region: ast.stmt) -> int:
+    defined_before = {node.arg for node in ast.walk(funcdef.args) if isinstance(node, ast.arg)}
+    used_after: set[str] = set()
+    region_loads: set[str] = set()
+    region_stores: set[str] = set()
+    buckets = {
+        "defined_before": defined_before,
+        "used_after": used_after,
+        "region_loads": region_loads,
+        "region_stores": region_stores,
+    }
+
+    start = region.lineno
+    end = region.end_lineno or start
+
+    for node in ast.walk(funcdef):
+        role = _name_coupling_role(node, start, end)
+        if role is not None:
+            bucket, name = role
+            buckets[bucket].add(name)
+
+    inputs = region_loads & defined_before
+    outputs = region_stores & used_after
+    return len(inputs) + len(outputs)
+
+
+def _name_coupling_role(node: ast.AST, start: int, end: int) -> tuple[str, str] | None:
+    if not isinstance(node, ast.Name):
+        return None
+    lineno = node.lineno
+    if lineno < start and isinstance(node.ctx, ast.Store):
+        return "defined_before", node.id
+    if lineno > end and isinstance(node.ctx, ast.Load):
+        return "used_after", node.id
+    if start <= lineno <= end and isinstance(node.ctx, ast.Load):
+        return "region_loads", node.id
+    if start <= lineno <= end and isinstance(node.ctx, ast.Store):
+        return "region_stores", node.id
+    return None
+
+
+def _dispatch_reduction(region: ast.stmt) -> int:
+    if isinstance(region, ast.If):
+        arms = _elif_arms(region) if _is_simple_equality_chain(region) else 0
+        return arms if arms >= _DISPATCH_MIN_ARMS else 0
+    if isinstance(region, ast.Match):
+        if _has_structural_patterns(region):
+            return 0
+        cases = len(region.cases)
+        return cases - 1 if cases >= _DISPATCH_MIN_CASES else 0
+    return 0
+
+
+def _is_simple_equality_chain(node: ast.If) -> bool:
+    tests = _if_chain_tests(node)
+    subject: str | None = None
+    for test in tests:
+        parsed = _simple_equality_test(test)
+        if parsed is None:
+            return False
+        current_subject, _key = parsed
+        if subject is None:
+            subject = current_subject
+        elif current_subject != subject:
+            return False
+    return subject is not None
+
+
+def _if_chain_tests(node: ast.If) -> list[ast.expr]:
+    tests = [node.test]
+    current = node
+    while len(current.orelse) == 1 and isinstance(current.orelse[0], ast.If):
+        current = current.orelse[0]
+        tests.append(current.test)
+    return tests
+
+
+def _simple_equality_test(test: ast.expr) -> tuple[str, object] | None:
+    if not (
+        isinstance(test, ast.Compare)
+        and len(test.ops) == 1
+        and isinstance(test.ops[0], ast.Eq)
+        and len(test.comparators) == 1
+    ):
+        return None
+    left = _dispatch_subject(test.left)
+    right = _dispatch_subject(test.comparators[0])
+    left_key = _dispatch_key(test.left)
+    right_key = _dispatch_key(test.comparators[0])
+    if left is not None and right_key is not None:
+        return left, right_key
+    if right is not None and left_key is not None:
+        return right, left_key
+    return None
+
+
+def _dispatch_subject(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name | ast.Attribute | ast.Subscript):
+        return ast.unparse(node)
+    return None
+
+
+def _dispatch_key(node: ast.AST) -> object | None:
+    if isinstance(node, ast.Constant) and isinstance(
+        node.value, (str, int, float, bool, bytes, type(None))
+    ):
+        return node.value
+    return None
+
+
+def _has_structural_patterns(node: ast.Match) -> bool:
+    for case in node.cases:
+        if case.guard is not None:
+            return True
+        if not _is_simple_pattern(case.pattern):
+            return True
+    return False
+
+
+def _is_simple_pattern(pattern: ast.pattern) -> bool:
+    if isinstance(pattern, (ast.MatchValue, ast.MatchSingleton)):
+        return True
+    if isinstance(pattern, ast.MatchAs) and pattern.pattern is None:
+        return True
+    if isinstance(pattern, ast.MatchOr):
+        return all(_is_simple_pattern(p) for p in pattern.patterns)
+    return False
+
+
+def _elif_arms(node: ast.If) -> int:
+    arms = 0
+    current = node
+    while len(current.orelse) == 1 and isinstance(current.orelse[0], ast.If):
+        arms += 1
+        current = current.orelse[0]
+    return arms
+
+
+def _predicate_suggestions(
+    funcdef: AnyFuncdef, breakdown: list[Contribution], total: int
+) -> list[Suggestion]:
+    unsafe_lines = _predicate_unsafe_lines(funcdef)
+    return [
+        _make("extract_predicate", c.lineno, c.lineno, c.points, total)
+        for c in breakdown
+        if c.label == "bool-op"
+        and c.points >= _PREDICATE_MIN_POINTS
+        and c.lineno not in unsafe_lines
+    ]
+
+
+def _predicate_unsafe_lines(funcdef: AnyFuncdef) -> set[int]:
+    return {
+        node.lineno
+        for node in ast.walk(funcdef)
+        if isinstance(node, ast.BoolOp)
+        and any(isinstance(child, ast.NamedExpr) for child in ast.walk(node))
+    }
+
+
+def _select(candidates: list[Suggestion]) -> list[Suggestion]:
+    good = [c for c in candidates if c.estimated_reduction >= _MIN_REDUCTION]
+    good.sort(key=lambda c: (-c.estimated_reduction, c.line_start))
+    out: list[Suggestion] = []
+    for candidate in good:
+        if any(_contains(s, candidate) for s in out):
+            continue
+        out.append(candidate)
+        if len(out) == _MAX_SUGGESTIONS:
+            break
+    return out
+
+
+def _contains(outer: Suggestion, inner: Suggestion) -> bool:
+    return (
+        outer.kind == inner.kind
+        and outer.line_start <= inner.line_start
+        and outer.line_end >= inner.line_end
+    )

cognitive_complexity/report.py

@@ -0,0 +1,103 @@
+"""Machine-readable JSON report, so cococo can sit in a pipeline.
+
+Each shown function is emitted with its score, the per-construct breakdown, and
+the refactor suggestions. The shape is stable and flat enough to filter with
+``jq`` or feed to an agent.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from cognitive_complexity.common_types import ScoredFunction, SkippedFile
+from cognitive_complexity.refactor import suggest_refactors
+
+
+def _path_key(path: Path, root: Path | None) -> str:
+    if root is None:
+        return str(path)
+    resolved_path = path.resolve()
+    resolved_root = root.resolve()
+    try:
+        return resolved_path.relative_to(resolved_root).as_posix()
+    except ValueError:
+        return resolved_path.as_posix()
+
+
+def func_key(func: ScoredFunction, root: Path | None = None) -> str:
+    """Stable identity for a function across runs, used as the baseline key."""
+    return f"{_path_key(func.path, root)}::{func.qualname}"
+
+
+def is_over(
+    func: ScoredFunction,
+    max_: int | None,
+    baseline: dict[str, int] | None,
+    baseline_root: Path | None = None,
+) -> bool:
+    """Whether ``func`` fails the gate: over ``--max``, not ignored, not grandfathered.
+
+    With a ``baseline`` the effective ceiling for a recorded function is the
+    higher of ``--max`` and its baseline score, so a known offender passes at its
+    recorded score and fails only when it regresses above it; a function absent
+    from the baseline is gated at ``--max`` like any new code.
+    """
+    if max_ is None or func.ignored:
+        return False
+    if baseline is None:
+        ceiling = max_
+    else:
+        recorded = baseline.get(func_key(func, baseline_root), baseline.get(func_key(func), max_))
+        ceiling = max(max_, recorded)
+    return func.score > ceiling
+
+
+def build_report(
+    funcs: list[ScoredFunction],
+    max_: int | None,
+    min_: int,
+    skipped: list[SkippedFile],
+    files_scanned: int,
+    baseline: dict[str, int] | None = None,
+    baseline_root: Path | None = None,
+) -> dict[str, object]:
+    """Assemble the JSON-able report for the already-filtered ``funcs``.
+
+    ``files_scanned`` and ``skipped`` make scan coverage explicit so a consumer
+    can tell a clean scan from a partial one: ``"exceeded": 0`` over a tree where
+    files failed to parse is no longer indistinguishable from a genuinely clean
+    tree. ``over``/``exceeded`` honor ``# cococo: ignore`` and the baseline.
+    """
+    entries = [_func_entry(func, max_, baseline, baseline_root) for func in funcs]
+    return {
+        "max": max_,
+        "min": min_,
+        "functions": entries,
+        "exceeded": sum(1 for entry in entries if entry["over"]),
+        "files_scanned": files_scanned,
+        "skipped": [{"path": str(s.path), "reason": s.reason} for s in skipped],
+    }
+
+
+def _func_entry(
+    func: ScoredFunction,
+    max_: int | None,
+    baseline: dict[str, int] | None,
+    baseline_root: Path | None,
+) -> dict[str, object]:
+    breakdown = func.breakdown
+    suggestions = suggest_refactors(func.funcdef, breakdown)
+    return {
+        "path": str(func.path),
+        "lineno": func.lineno,
+        "qualname": func.qualname,
+        "complexity": func.score,
+        "over": is_over(func, max_, baseline, baseline_root),
+        "breakdown": [c._asdict() for c in breakdown],
+        "suggestions": [s._asdict() for s in suggestions],
+    }
+
+
+def to_json(report: dict[str, object]) -> str:
+    return json.dumps(report, indent=2)