codecoco 3.5.1__py3-none-any.whl

cognitive_complexity/autofix.py

@@ -0,0 +1,238 @@
+"""Safe, formatting-preserving guard-clause flattening for ``--fix``.
+
+Only one transform, and only where it is provably behavior-preserving: an ``if``
+with no ``else`` that is the *last* statement of a function body or loop body is
+rewritten into an early ``return``/``continue`` guard, and its body de-indented
+one level. Because the ``if`` is last, returning/continuing early when the
+condition is false changes nothing. Anything that fails the strict preconditions
+in :func:`_is_safe_guard` is left exactly as it was.
+
+Edits are made on the source text (not via ``ast.unparse``) so comments and
+formatting in the untouched body survive.
+
+Why hand-rolled text surgery and not a CST library (LibCST)? LibCST was
+considered and rejected: its headline win — comment/whitespace preservation — is
+already achieved here for the single transform that exists, and cococo declares
+zero runtime dependencies by design (it is a low-level dependency of other
+pipelines), a posture LibCST's native extension + ``pyyaml`` would break.
+**Reopen trigger:** this calculus holds only because there is exactly one
+provably-safe transform. When a *second* non-trivial rewrite is added, re-run the
+LibCST bake-off — string surgery does not compose across transforms (each one
+re-derives indent units, newline style, and segment boundaries), so at N>=2 the
+decision flips to adopting a CST.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import tempfile
+from pathlib import Path
+
+from cognitive_complexity.common_types import is_funcdef
+
+# The transform is idempotent (a flattened guard is no longer the last statement
+# of its block), so this only caps pathological input; it is never reached in
+# practice.
+_MAX_PASSES = 1000
+
+_LOOP_TYPES = (ast.For, ast.AsyncFor, ast.While)
+_BREAKER_TYPES = (
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.If,
+    ast.IfExp,
+    ast.ExceptHandler,
+    ast.Match,
+)
+
+
+def fix_source(source: str) -> tuple[str, int]:
+    """Apply every safe guard-clause flattening in ``source``.
+
+    Returns the rewritten source and the number of guards applied. Raises
+    ``SyntaxError`` if ``source`` does not parse.
+    """
+    fixes = 0
+    for _ in range(_MAX_PASSES):
+        tree = ast.parse(source)
+        target = _find_guard(tree, source)
+        if target is None:
+            break
+        node, keyword = target
+        source = _apply_guard(source, node, keyword)
+        fixes += 1
+    return source, fixes
+
+
+def _find_guard(tree: ast.AST, source: str) -> tuple[ast.If, str] | None:
+    candidates: list[tuple[ast.If, str]] = []
+    for block, keyword in _guarded_blocks(tree):
+        last = block[-1] if block else None
+        if isinstance(last, ast.If) and _is_safe_guard(last, source):
+            candidates.append((last, keyword))
+    if not candidates:
+        return None
+    return min(candidates, key=lambda c: c[0].lineno)
+
+
+def _guarded_blocks(tree: ast.AST) -> list[tuple[list[ast.stmt], str]]:
+    blocks: list[tuple[list[ast.stmt], str]] = []
+    for node in ast.walk(tree):
+        if is_funcdef(node):
+            blocks.append((node.body, "return"))
+        elif isinstance(node, _LOOP_TYPES):
+            blocks.append((node.body, "continue"))
+    return blocks
+
+
+def _is_safe_guard(node: ast.If, source: str) -> bool:
+    if node.orelse or not node.body:
+        return False
+    body_first = node.body[0]
+    if body_first.lineno <= node.lineno:  # single-line `if x: ...`
+        return False
+    if node.test.lineno != (node.test.end_lineno or node.test.lineno):  # multi-line test
+        return False
+    if not _has_nested_breaker(node.body):  # flattening would save nothing
+        return False
+    if _has_multiline_string(node.body):  # blind dedent would corrupt string content
+        return False
+    return _indent_unit(node, source) > 0
+
+
+def _has_nested_breaker(body: list[ast.stmt]) -> bool:
+    return any(isinstance(inner, _BREAKER_TYPES) for stmt in body for inner in ast.walk(stmt))
+
+
+def _has_multiline_string(body: list[ast.stmt]) -> bool:
+    """True if any string / f-string literal in the body spans multiple lines.
+
+    Dedenting such a body line-by-line (``_dedent``) would strip leading spaces
+    that are *content* of the literal, silently changing its value — so the
+    guard is left untouched rather than risk corrupting source.
+    """
+    return any(
+        isinstance(inner, (ast.Constant, ast.JoinedStr)) and inner.lineno != inner.end_lineno
+        for stmt in body
+        for inner in ast.walk(stmt)
+    )
+
+
+def _leading_ws(line: str) -> str:
+    return line[: len(line) - len(line.lstrip())]
+
+
+def _indent_unit(node: ast.If, source: str) -> int:
+    """Spaces the body sits below the ``if``; 0 if either uses tab indentation."""
+    lines = source.splitlines()
+    if_ws = _leading_ws(lines[node.lineno - 1])
+    body_ws = _leading_ws(lines[node.body[0].lineno - 1])
+    if "\t" in if_ws or "\t" in body_ws:
+        return 0
+    return len(body_ws) - len(if_ws)
+
+
+def _apply_guard(source: str, node: ast.If, keyword: str) -> str:
+    lines = source.splitlines(keepends=True)
+    header_idx = node.lineno - 1
+    end = node.end_lineno or node.lineno
+    header = lines[header_idx]
+    newline = "\r\n" if header.endswith("\r\n") else "\n"
+    if_indent = _leading_ws(header)
+    unit = _indent_unit(node, source)
+    body_indent = if_indent + " " * unit
+    condition = _inverted_condition(node.test, source)
+    new_header = f"{if_indent}if {condition}:{newline}{body_indent}{keyword}{newline}"
+
+    out = lines[:header_idx]
+    out.append(new_header)
+    out.extend(_dedent(lines[i], unit) for i in range(header_idx + 1, end))
+    out.extend(lines[end:])
+    return "".join(out)
+
+
+def _dedent(line: str, unit: int) -> str:
+    return line[unit:] if line[:unit] == " " * unit else line
+
+
+# Membership/identity comparisons whose negation is *guaranteed* to be another
+# comparison by the language spec: ``x not in y`` is defined as ``not (x in y)``
+# and ``x is not y`` as ``not (x is y)``. Ordering and equality operators are
+# deliberately absent — ``not (x < y)`` differs from ``x >= y`` for NaN, and a
+# class may define ``__eq__``/``__ne__`` inconsistently — so those keep the safe
+# ``not (...)`` wrapper rather than risk a behaviour change.
+_NEGATED_CMP: dict[type[ast.cmpop], str] = {
+    ast.In: "not in",
+    ast.NotIn: "in",
+    ast.Is: "is not",
+    ast.IsNot: "is",
+}
+
+# ``not X`` reassociates when ``X`` binds looser than ``not`` (``not a and b`` is
+# ``(not a) and b``), so these constructs need the wrapping parens; calls, names,
+# and attributes bind tighter and the parens would be redundant noise a formatter
+# strips. ``Compare`` is included because the membership/identity cases that *can*
+# be inverted cleanly are flipped earlier (in :func:`_flip_comparison`) and never
+# reach here — only the ones kept as ``not (...)`` for safety (ordering, equality,
+# chained) fall through, and ``not k in a in b`` without parens would still trip
+# the very ``E713`` lint we are trying to avoid.
+_NEEDS_PARENS = (ast.BoolOp, ast.IfExp, ast.Lambda, ast.NamedExpr, ast.Compare)
+
+
+def _inverted_condition(test: ast.expr, source: str) -> str:
+    if isinstance(test, ast.UnaryOp) and isinstance(test.op, ast.Not):
+        inner = ast.get_source_segment(source, test.operand)
+        if inner is not None:
+            return inner
+    flipped = _flip_comparison(test, source)
+    if flipped is not None:
+        return flipped
+    segment = ast.get_source_segment(source, test)
+    if isinstance(test, _NEEDS_PARENS):
+        return f"not ({segment})"
+    return f"not {segment}"
+
+
+def _flip_comparison(test: ast.expr, source: str) -> str | None:
+    """Negate a single membership/identity comparison by flipping its operator.
+
+    Returns ``None`` for anything that is not a one-operator ``in``/``is``
+    comparison — chained comparisons (``a in b in c``), other operators, and
+    non-comparisons fall back to the ``not (...)`` wrapper in the caller.
+    """
+    if not isinstance(test, ast.Compare) or len(test.ops) != 1:
+        return None
+    operator = _NEGATED_CMP.get(type(test.ops[0]))
+    if operator is None:
+        return None
+    # Operands of a freshly-parsed comparison always carry position info, so
+    # get_source_segment never returns None here — same assumption the caller
+    # makes for the whole-test segment.
+    left = ast.get_source_segment(source, test.left)
+    right = ast.get_source_segment(source, test.comparators[0])
+    return f"{left} {operator} {right}"
+
+
+def atomic_write(path: Path, data: str) -> None:
+    """Overwrite ``path`` with ``data`` atomically, preserving its file mode.
+
+    Writes to a temp file in the same directory, fsyncs it, then ``os.replace``s
+    it over ``path`` — atomic within a filesystem, so a crash mid-write leaves
+    the original file intact rather than truncated/half-written. The temp file is
+    removed if anything fails (including on interrupt). ``newline=""`` keeps the
+    data's line endings byte-for-byte (the transform may emit ``\\r\\n``).
+    """
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    tmp_file = Path(tmp)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        tmp_file.chmod(path.stat().st_mode)
+        tmp_file.replace(path)
+    except BaseException:
+        tmp_file.unlink(missing_ok=True)
+        raise

cognitive_complexity/cli.py

@@ -0,0 +1,360 @@
+"""cococo — code cognitive complexity, on the command line.
+
+Scores every function and method in the given Python files/directories with
+:func:`cognitive_complexity.api.get_cognitive_complexity` and prints them
+worst-first. With ``--max`` it doubles as a gate: it exits non-zero when any
+function exceeds the ceiling, reporting each offender with concrete refactor
+suggestions.
+
+Usage::
+
+    cococo src/                  # list every function, worst first
+    cococo src/ --max 20         # gate: fail (with suggestions) above 20
+    cococo a.py b.py --min 10    # only show functions scoring >= 10
+    cococo src/ --max 20 --json  # machine-readable report for a pipeline
+    cococo src/ --fix            # apply safe guard-clause rewrites in place
+    cococo src/ --nested fold    # pre-2.0.0 scoring (fold nested defs into parent)
+    cococo src/ --max 20 --baseline .cococo.json   # ratchet: fail only on regressions
+    cococo --explain a.py::Klass.method   # break down one function
+    cococo --explain a.py:42              # ...by line number
+
+Exit codes in gate mode: 0 = within ceiling, 1 = offenders found, 2 = the gate
+could not be trusted (nothing scanned, a file skipped, or a --fix write failed).
+A function can suppress itself from the gate with a ``# cococo: ignore`` comment
+on its ``def`` line.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from cognitive_complexity.api import Contribution, get_cognitive_complexity_breakdown
+from cognitive_complexity.autofix import atomic_write, fix_source
+from cognitive_complexity.common_types import AnyFuncdef, ScoredFunction, SkippedFile
+from cognitive_complexity.discovery import find_function, iter_python_files, parse_target, scan
+from cognitive_complexity.refactor import suggest_refactors
+from cognitive_complexity.report import build_report, func_key, is_over, to_json
+
+
+class BaselineError(Exception):
+    """The baseline file could not be trusted."""
+
+
+def _format_breakdown(
+    funcdef: AnyFuncdef,
+    qualname: str,
+    path: Path,
+    breakdown: list[Contribution],
+) -> str:
+    total = sum(c.points for c in breakdown)
+    lines = [f"{qualname}  ({path}:{funcdef.lineno})  cognitive complexity = {total}"]
+    if not breakdown:
+        lines.append("  (no scored constructs — flat function)")
+        return "\n".join(lines)
+    lines.append(f"  {'line':>6}  {'pts':>3}  {'nest':>4}  construct")
+    for c in sorted(breakdown, key=lambda c: (c.lineno, -c.points)):
+        indent = "  " * c.nesting
+        if c.nesting_counted and c.nesting:
+            note = f"(+{c.points - c.nesting} base, +{c.nesting} nesting)"
+        else:
+            note = f"(+{c.points})"
+        lines.append(f"  {c.lineno:>6}  {c.points:>3}  {c.nesting:>4}  {indent}{c.label}  {note}")
+    return "\n".join(lines)
+
+
+def explain(target: str, fold_nested: bool = False) -> int:
+    """Print a per-construct cognitive-complexity breakdown for one function."""
+    path, qualname, lineno = parse_target(target)
+    try:
+        funcdef, qual = find_function(path, qualname, lineno, fold_nested)
+    except (LookupError, OSError, UnicodeDecodeError, SyntaxError, RecursionError) as exc:
+        print(f"cococo: {exc}", file=sys.stderr)
+        return 1
+    breakdown = get_cognitive_complexity_breakdown(funcdef, fold_nested)
+    print(_format_breakdown(funcdef, qual, path, breakdown))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cococo", description=__doc__.splitlines()[0])
+    parser.add_argument("paths", nargs="*", help="Python files or directories to scan")
+    parser.add_argument(
+        "--max",
+        type=int,
+        default=None,
+        help="ceiling: exit non-zero and show only functions above it",
+    )
+    parser.add_argument(
+        "--min", type=int, default=0, help="only list functions scoring at least this much"
+    )
+    parser.add_argument(
+        "--explain",
+        metavar="FILE::QUAL",
+        default=None,
+        help="break down one function: FILE.py::qualname, FILE.py:LINE, or FILE.py",
+    )
+    parser.add_argument(
+        "--json",
+        dest="as_json",
+        action="store_true",
+        help="emit a machine-readable JSON report to stdout (for pipelines)",
+    )
+    parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="apply safe guard-clause rewrites in place before reporting",
+    )
+    parser.add_argument(
+        "--nested",
+        choices=("unit", "fold"),
+        default="unit",
+        help="score named nested defs as their own units (default) or fold them "
+        "into the enclosing function (pre-2.0.0 compatibility)",
+    )
+    parser.add_argument(
+        "--baseline",
+        metavar="FILE",
+        default=None,
+        help="ratchet: record current scores to FILE if missing, else fail only on "
+        "functions that regress above their recorded score (requires --max)",
+    )
+    args = parser.parse_args(argv)
+    fold_nested = args.nested == "fold"
+
+    if args.explain is not None:
+        return explain(args.explain, fold_nested)
+    if not args.paths:
+        parser.error("the following arguments are required: paths (or use --explain)")
+    if args.baseline is not None and args.max is None:
+        parser.error("--baseline requires --max (the ceiling for code not in the baseline)")
+
+    fix_failures = _apply_fixes(args.paths) if args.fix else 0
+
+    functions, skipped, scanned = scan(args.paths, fold_nested)
+    try:
+        baseline, baseline_root = _baseline_for_scan(args.baseline, functions, skipped)
+    except BaselineError as exc:
+        print(f"cococo: {exc}", file=sys.stderr)
+        return 2
+    _warn_unused_ignores(functions, args.max)
+    scan_code = _scan_exit_code(
+        functions, skipped, scanned, args.max, args.as_json, args.min, baseline, baseline_root
+    )
+    # A failed --fix write, or a file skipped under a gate, is a hard failure (2)
+    # regardless of whether the functions that *did* scan stayed within --max.
+    if fix_failures or (skipped and args.max is not None):
+        return 2
+    return scan_code
+
+
+def _baseline_for_scan(
+    raw_path: str | None,
+    functions: list[ScoredFunction],
+    skipped: list[SkippedFile],
+) -> tuple[dict[str, int] | None, Path | None]:
+    """Load/create the baseline only when the scan is trusted enough to do so."""
+    if raw_path is None:
+        return None, None
+    path = Path(raw_path)
+    root = path.parent
+    if not path.exists() and (not functions or skipped):
+        return None, root
+    return _load_or_create_baseline(path, functions), root
+
+
+def _load_or_create_baseline(path: Path, functions: list[ScoredFunction]) -> dict[str, int]:
+    """Load the baseline at ``path``, or create it from current scores and pass.
+
+    A missing file establishes the baseline (every current score recorded) so the
+    first run grandfathers the whole codebase; later runs compare against it.
+    """
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise BaselineError(f"invalid baseline {path}: {exc}") from exc
+        return _validate_baseline(path, loaded)
+    baseline = {func_key(f, path.parent): f.score for f in functions}
+    try:
+        path.write_text(json.dumps(baseline, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    except OSError as exc:
+        raise BaselineError(f"invalid baseline {path}: {exc}") from exc
+    print(f"cococo: wrote baseline for {len(baseline)} function(s) to {path}", file=sys.stderr)
+    return baseline
+
+
+def _validate_baseline(path: Path, loaded: object) -> dict[str, int]:
+    if not isinstance(loaded, dict) or any(
+        not isinstance(key, str) or type(value) is not int for key, value in loaded.items()
+    ):
+        raise BaselineError(f"invalid baseline {path}: expected dict[str, int]")
+    return loaded
+
+
+def _warn_unused_ignores(functions: list[ScoredFunction], max_: int | None) -> None:
+    """Warn about ``# cococo: ignore`` directives on functions already within the gate."""
+    if max_ is None:
+        return
+    for f in functions:
+        if f.ignored and f.score <= max_:
+            print(
+                f"cococo: unused '# cococo: ignore' on {f.qualname} "
+                f"({f.path}:{f.lineno}) — score {f.score} is within {max_}",
+                file=sys.stderr,
+            )
+
+
+def _scan_exit_code(
+    functions: list[ScoredFunction],
+    skipped: list[SkippedFile],
+    scanned: int,
+    max_: int | None,
+    as_json: bool,
+    min_: int,
+    baseline: dict[str, int] | None,
+    baseline_root: Path | None,
+) -> int:
+    if as_json:
+        return _report_json(functions, skipped, scanned, max_, min_, baseline, baseline_root)
+    if not functions:
+        return _empty_scan_exit(max_)
+    return _report(functions, max_, min_, baseline, baseline_root)
+
+
+def _empty_scan_exit(max_: int | None) -> int:
+    """No functions matched the paths (text mode). Stay honest in gate mode.
+
+    A ``--max`` gate that scans zero functions (a typo'd path, a renamed dir, a
+    glob that expanded to nothing) is a misconfiguration, not a pass: it returns
+    a distinct code (2) so CI cannot go green on a gate that gated nothing.
+    Without ``--max`` an empty scan is merely informational (exit 0). (The
+    ``--json`` empty case is handled by :func:`_report_json`, which still emits a
+    valid report.)
+    """
+    print("cococo: no Python functions found", file=sys.stderr)
+    if max_ is not None:
+        print("cococo: no functions scanned — check the paths given to the gate", file=sys.stderr)
+        return 2
+    return 0
+
+
+def _shown(functions: list[ScoredFunction], max_: int | None, min_: int) -> list[ScoredFunction]:
+    threshold = max_ if max_ is not None else min_
+    return sorted(
+        (f for f in functions if f.score > threshold or (max_ is None and f.score >= min_)),
+        key=lambda f: f.score,
+        reverse=True,
+    )
+
+
+def _apply_fixes(paths: list[str]) -> int:
+    """Rewrite safe guard-clause patterns in place; return the write-failure count.
+
+    Each changed file is written atomically (a crash can't truncate the
+    original), and both read/parse errors and write errors are recorded-and-
+    skipped so one bad file never aborts the batch. Per-file outcomes go to
+    stderr; the returned count lets the caller fail the exit code when a write
+    did not land.
+    """
+    changed = 0
+    applied = 0
+    failed = 0
+    for path in iter_python_files(paths):
+        try:
+            source = path.read_text(encoding="utf-8")
+            new_source, count = fix_source(source)
+        except (OSError, UnicodeDecodeError, SyntaxError, RecursionError):
+            continue
+        if not count:
+            continue
+        try:
+            atomic_write(path, new_source)
+        except OSError as exc:
+            print(f"cococo: FAILED to write {path}: {exc}", file=sys.stderr)
+            failed += 1
+            continue
+        print(f"cococo: fixed {path} ({count} guard(s))", file=sys.stderr)
+        changed += 1
+        applied += count
+    print(
+        f"cococo: applied {applied} guard-clause fix(es) across {changed} file(s)",
+        file=sys.stderr,
+    )
+    return failed
+
+
+def _report(
+    functions: list[ScoredFunction],
+    max_: int | None,
+    min_: int,
+    baseline: dict[str, int] | None,
+    baseline_root: Path | None,
+) -> int:
+    """Print the scored functions and, when ``max_`` is set, gate on it."""
+    for f in _shown(functions, max_, min_):
+        print(f"{f.score:4d}  {f.path}:{f.lineno}  {f.qualname}")
+
+    if max_ is None:
+        return 0
+    over = [f for f in functions if is_over(f, max_, baseline, baseline_root)]
+    if over:
+        _print_gate_failure(over, max_)
+        return 1
+    print(f"cococo: all {len(functions)} functions within cognitive complexity {max_}")
+    return 0
+
+
+def _report_json(
+    functions: list[ScoredFunction],
+    skipped: list[SkippedFile],
+    scanned: int,
+    max_: int | None,
+    min_: int,
+    baseline: dict[str, int] | None,
+    baseline_root: Path | None,
+) -> int:
+    report = build_report(
+        _shown(functions, max_, min_),
+        max_,
+        min_,
+        skipped,
+        scanned,
+        baseline,
+        baseline_root,
+    )
+    print(to_json(report))
+    if not functions and max_ is not None:
+        return 2  # gate scanned nothing — fail loud even in JSON mode
+    return 1 if max_ is not None and report["exceeded"] else 0
+
+
+def _print_gate_failure(over: list[ScoredFunction], max_: int) -> None:
+    print(
+        f"\ncococo: {len(over)} function(s) exceed cognitive complexity {max_}",
+        file=sys.stderr,
+    )
+    for f in sorted(over, key=lambda f: f.score, reverse=True):
+        _print_suggestions(f, max_)
+
+
+def _print_suggestions(f: ScoredFunction, max_: int) -> None:
+    suggestions = suggest_refactors(f.funcdef, f.breakdown)
+    print(f"  {f.path}:{f.lineno} {f.qualname} = {f.score} (>{max_})", file=sys.stderr)
+    if not suggestions:
+        print("    (no mechanical refactor found; split it by responsibility)", file=sys.stderr)
+        return
+    for s in suggestions:
+        fix = " [--fix]" if s.autofixable else ""
+        print(
+            f"    - {s.title} "
+            f"(lines {s.line_start}-{s.line_end}, ~-{s.estimated_reduction} "
+            f"-> {s.estimated_complexity_after}){fix}",
+            file=sys.stderr,
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

cognitive_complexity/common_types.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import TYPE_CHECKING, NamedTuple, TypeGuard
+
+if TYPE_CHECKING:
+    from cognitive_complexity.api import Contribution
+
+AnyFuncdef = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+def is_funcdef(node: ast.AST) -> TypeGuard[AnyFuncdef]:
+    """True if ``node`` is a (possibly async) function definition.
+
+    One definition of "scorable function unit" for every tree-walker; the
+    ``TypeGuard`` return preserves type narrowing at the call sites (e.g. reading
+    ``node.name``) under strict mypy.
+    """
+    return isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+
+
+class ScoredFunction(NamedTuple):
+    """A scored function plus the node it was scored from (for breakdowns/fixes).
+
+    ``breakdown`` is the per-construct scoring computed once at discovery time;
+    ``score`` is its points sum. Carrying it avoids a second walk in the JSON
+    report and gate-suggestion paths. ``ignored`` is true when the function's
+    ``def`` line carries a ``# cococo: ignore`` directive, which excludes it from
+    the ``--max`` gate.
+    """
+
+    score: int
+    path: Path
+    lineno: int
+    qualname: str
+    funcdef: AnyFuncdef
+    breakdown: list[Contribution]
+    ignored: bool = False
+
+
+class SkippedFile(NamedTuple):
+    """A file the scanner could not read, parse, or score, with the reason why."""
+
+    path: Path
+    reason: str