codecoco 3.5.1__tar.gz → 3.6.0__tar.gz

{codecoco-3.5.1 → codecoco-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecoco
-Version: 3.5.1
+Version: 3.6.0
 Summary: Library and CLI to compute the cognitive complexity of Python functions
 Home-page: https://github.com/qwhex/cococo
 Author: Mice Pápai
@@ -65,9 +65,10 @@ pip install git+https://github.com/qwhex/cococo
 ### Command line
 
 ```bash
-cococo src/                  # score every function, worst first
+cococo src/                  # score worst-first, with refactor suggestions inline
 cococo src/ --max 20         # gate: exit non-zero if any function exceeds 20
-cococo a.py b.py --min 10    # only show functions scoring >= 10
+cococo a.py b.py --min 10    # only list functions scoring >= 10
+cococo src/ --suggest-min 10 # only attach suggestions to 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 the parent
@@ -91,19 +92,23 @@ scored by its inner function) as a migration aid; the same is available in the
 library as `get_cognitive_complexity(funcdef, fold_nested=True)`. See
 [CHANGELOG.md](CHANGELOG.md).
 
-### Refactor suggestions on a failing gate
+### Refactor suggestions
 
-When `--max` is exceeded, each offending function is reported on stderr together
-with a few concrete, mechanical refactors and an estimated complexity drop — so
-a human (or an agent) reading the failure knows what to do next:
+Beyond reporting a score, cococo points at what to *do* about a complex
+function: the default listing prints concrete, mechanical refactors inline —
+each with the lines it touches and an estimated complexity drop:
 
 ```text
-cococo: 1 function(s) exceed cognitive complexity 5
-  src/load.py:42 load = 14 (>5)
+  14  src/load.py:42  load
     - Extract this block into a helper function (lines 50-61, ~-7 -> 7)
     - Flatten nested block with a guard clause (lines 45-61, ~-3 -> 11) [--fix]
 ```
 
+`--suggest-min N` attaches suggestions only to functions scoring at least `N`
+(it defaults to `--min`), to focus the output on the worst offenders. Under a
+`--max` gate the offending functions are reported on stderr with the same
+suggestions instead, so a failing CI step says exactly what to fix.
+
 Suggestions tagged `[--fix]` can be applied automatically. `--fix` rewrites only
 transforms it can prove keep behavior identical (an `if` with no `else` that is
 the last statement of a function or loop body becomes an early

{codecoco-3.5.1 → codecoco-3.6.0}/README.md

@@ -30,9 +30,10 @@ pip install git+https://github.com/qwhex/cococo
 ### Command line
 
 ```bash
-cococo src/                  # score every function, worst first
+cococo src/                  # score worst-first, with refactor suggestions inline
 cococo src/ --max 20         # gate: exit non-zero if any function exceeds 20
-cococo a.py b.py --min 10    # only show functions scoring >= 10
+cococo a.py b.py --min 10    # only list functions scoring >= 10
+cococo src/ --suggest-min 10 # only attach suggestions to 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 the parent
@@ -56,19 +57,23 @@ scored by its inner function) as a migration aid; the same is available in the
 library as `get_cognitive_complexity(funcdef, fold_nested=True)`. See
 [CHANGELOG.md](CHANGELOG.md).
 
-### Refactor suggestions on a failing gate
+### Refactor suggestions
 
-When `--max` is exceeded, each offending function is reported on stderr together
-with a few concrete, mechanical refactors and an estimated complexity drop — so
-a human (or an agent) reading the failure knows what to do next:
+Beyond reporting a score, cococo points at what to *do* about a complex
+function: the default listing prints concrete, mechanical refactors inline —
+each with the lines it touches and an estimated complexity drop:
 
 ```text
-cococo: 1 function(s) exceed cognitive complexity 5
-  src/load.py:42 load = 14 (>5)
+  14  src/load.py:42  load
     - Extract this block into a helper function (lines 50-61, ~-7 -> 7)
     - Flatten nested block with a guard clause (lines 45-61, ~-3 -> 11) [--fix]
 ```
 
+`--suggest-min N` attaches suggestions only to functions scoring at least `N`
+(it defaults to `--min`), to focus the output on the worst offenders. Under a
+`--max` gate the offending functions are reported on stderr with the same
+suggestions instead, so a failing CI step says exactly what to fix.
+
 Suggestions tagged `[--fix]` can be applied automatically. `--fix` rewrites only
 transforms it can prove keep behavior identical (an `if` with no `else` that is
 the last statement of a function or loop body becomes an early

{codecoco-3.5.1 → codecoco-3.6.0}/codecoco.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecoco
-Version: 3.5.1
+Version: 3.6.0
 Summary: Library and CLI to compute the cognitive complexity of Python functions
 Home-page: https://github.com/qwhex/cococo
 Author: Mice Pápai
@@ -65,9 +65,10 @@ pip install git+https://github.com/qwhex/cococo
 ### Command line
 
 ```bash
-cococo src/                  # score every function, worst first
+cococo src/                  # score worst-first, with refactor suggestions inline
 cococo src/ --max 20         # gate: exit non-zero if any function exceeds 20
-cococo a.py b.py --min 10    # only show functions scoring >= 10
+cococo a.py b.py --min 10    # only list functions scoring >= 10
+cococo src/ --suggest-min 10 # only attach suggestions to 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 the parent
@@ -91,19 +92,23 @@ scored by its inner function) as a migration aid; the same is available in the
 library as `get_cognitive_complexity(funcdef, fold_nested=True)`. See
 [CHANGELOG.md](CHANGELOG.md).
 
-### Refactor suggestions on a failing gate
+### Refactor suggestions
 
-When `--max` is exceeded, each offending function is reported on stderr together
-with a few concrete, mechanical refactors and an estimated complexity drop — so
-a human (or an agent) reading the failure knows what to do next:
+Beyond reporting a score, cococo points at what to *do* about a complex
+function: the default listing prints concrete, mechanical refactors inline —
+each with the lines it touches and an estimated complexity drop:
 
 ```text
-cococo: 1 function(s) exceed cognitive complexity 5
-  src/load.py:42 load = 14 (>5)
+  14  src/load.py:42  load
     - Extract this block into a helper function (lines 50-61, ~-7 -> 7)
     - Flatten nested block with a guard clause (lines 45-61, ~-3 -> 11) [--fix]
 ```
 
+`--suggest-min N` attaches suggestions only to functions scoring at least `N`
+(it defaults to `--min`), to focus the output on the worst offenders. Under a
+`--max` gate the offending functions are reported on stderr with the same
+suggestions instead, so a failing CI step says exactly what to fix.
+
 Suggestions tagged `[--fix]` can be applied automatically. `--fix` rewrites only
 transforms it can prove keep behavior identical (an `if` with no `else` that is
 the last statement of a function or loop body becomes an early

codecoco-3.6.0/cognitive_complexity/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.6.0"

{codecoco-3.5.1 → codecoco-3.6.0}/cognitive_complexity/cli.py

@@ -2,15 +2,16 @@
 
 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.
+worst-first, with concrete refactor suggestions inline by default. With ``--max``
+it doubles as a gate: it exits non-zero when any function exceeds the ceiling,
+reporting each offender (with the same suggestions) on stderr.
 
 Usage::
 
-    cococo src/                  # list every function, worst first
+    cococo src/                  # list worst-first, with suggestions inline
     cococo src/ --max 20         # gate: fail (with suggestions) above 20
     cococo a.py b.py --min 10    # only show functions scoring >= 10
+    cococo src/ --suggest-min 10 # only suggest on 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)
@@ -35,7 +36,7 @@ from cognitive_complexity.api import Contribution, get_cognitive_complexity_brea
 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.refactor import Suggestion, suggest_refactors
 from cognitive_complexity.report import build_report, func_key, is_over, to_json
 
 
@@ -90,6 +91,14 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "--min", type=int, default=0, help="only list functions scoring at least this much"
     )
+    parser.add_argument(
+        "--suggest-min",
+        type=int,
+        default=None,
+        metavar="N",
+        help="show inline refactor suggestions for functions scoring at least N "
+        "(default: same as --min). Applies to the default listing, not the --max gate.",
+    )
     parser.add_argument(
         "--explain",
         metavar="FILE::QUAL",
@@ -123,6 +132,7 @@ def main(argv: list[str] | None = None) -> int:
     )
     args = parser.parse_args(argv)
     fold_nested = args.nested == "fold"
+    suggest_min = _resolve_suggest_min(args.suggest_min, args.min)
 
     if args.explain is not None:
         return explain(args.explain, fold_nested)
@@ -141,7 +151,15 @@ def main(argv: list[str] | None = None) -> int:
         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
+        functions,
+        skipped,
+        scanned,
+        args.max,
+        args.as_json,
+        args.min,
+        suggest_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.
@@ -207,6 +225,11 @@ def _warn_unused_ignores(functions: list[ScoredFunction], max_: int | None) -> N
             )
 
 
+def _resolve_suggest_min(suggest_min: int | None, min_: int) -> int:
+    """The suggestion threshold defaults to ``--min`` but can be tuned separately."""
+    return suggest_min if suggest_min is not None else min_
+
+
 def _scan_exit_code(
     functions: list[ScoredFunction],
     skipped: list[SkippedFile],
@@ -214,14 +237,17 @@ def _scan_exit_code(
     max_: int | None,
     as_json: bool,
     min_: int,
+    suggest_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)
+        return _report_json(
+            functions, skipped, scanned, max_, min_, suggest_min, baseline, baseline_root
+        )
     if not functions:
         return _empty_scan_exit(max_)
-    return _report(functions, max_, min_, baseline, baseline_root)
+    return _report(functions, max_, min_, suggest_min, baseline, baseline_root)
 
 
 def _empty_scan_exit(max_: int | None) -> int:
@@ -290,12 +316,18 @@ def _report(
     functions: list[ScoredFunction],
     max_: int | None,
     min_: int,
+    suggest_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}")
+    """Print the scored functions and, when ``max_`` is set, gate on it.
+
+    In the default listing (no ``--max``) each function scoring at least
+    ``suggest_min`` carries its refactor suggestions inline, so the actionable
+    advice is the default output rather than a gate-only diagnostic. Under a gate
+    the listing stays terse and suggestions are reported with the offenders.
+    """
+    _print_listing(_shown(functions, max_, min_), max_ is None, suggest_min)
 
     if max_ is None:
         return 0
@@ -313,6 +345,7 @@ def _report_json(
     scanned: int,
     max_: int | None,
     min_: int,
+    suggest_min: int,
     baseline: dict[str, int] | None,
     baseline_root: Path | None,
 ) -> int:
@@ -320,6 +353,7 @@ def _report_json(
         _shown(functions, max_, min_),
         max_,
         min_,
+        suggest_min,
         skipped,
         scanned,
         baseline,
@@ -331,6 +365,28 @@ def _report_json(
     return 1 if max_ is not None and report["exceeded"] else 0
 
 
+def _suggestion_line(s: Suggestion) -> str:
+    fix = " [--fix]" if s.autofixable else ""
+    return (
+        f"    - {s.title} "
+        f"(lines {s.line_start}-{s.line_end}, ~-{s.estimated_reduction} "
+        f"-> {s.estimated_complexity_after}){fix}"
+    )
+
+
+def _print_listing(shown: list[ScoredFunction], with_suggestions: bool, suggest_min: int) -> None:
+    """Print each function's score line to stdout, with suggestions inline when asked.
+
+    Listing mode shows only real suggestions; unlike the gate it stays silent when
+    none apply (no "no mechanical refactor found" line) so a clean listing is quiet.
+    """
+    for f in shown:
+        print(f"{f.score:4d}  {f.path}:{f.lineno}  {f.qualname}")
+        if with_suggestions and f.score >= suggest_min:
+            for s in suggest_refactors(f.funcdef, f.breakdown):
+                print(_suggestion_line(s))
+
+
 def _print_gate_failure(over: list[ScoredFunction], max_: int) -> None:
     print(
         f"\ncococo: {len(over)} function(s) exceed cognitive complexity {max_}",
@@ -347,13 +403,7 @@ def _print_suggestions(f: ScoredFunction, max_: int) -> None:
         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,
-        )
+        print(_suggestion_line(s), file=sys.stderr)
 
 
 if __name__ == "__main__":  # pragma: no cover

{codecoco-3.5.1 → codecoco-3.6.0}/cognitive_complexity/report.py

@@ -57,6 +57,7 @@ def build_report(
     funcs: list[ScoredFunction],
     max_: int | None,
     min_: int,
+    suggest_min: int,
     skipped: list[SkippedFile],
     files_scanned: int,
     baseline: dict[str, int] | None = None,
@@ -68,8 +69,9 @@ def build_report(
     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.
+    Suggestions are attached to functions scoring at least ``suggest_min``.
     """
-    entries = [_func_entry(func, max_, baseline, baseline_root) for func in funcs]
+    entries = [_func_entry(func, max_, suggest_min, baseline, baseline_root) for func in funcs]
     return {
         "max": max_,
         "min": min_,
@@ -83,11 +85,12 @@ def build_report(
 def _func_entry(
     func: ScoredFunction,
     max_: int | None,
+    suggest_min: int,
     baseline: dict[str, int] | None,
     baseline_root: Path | None,
 ) -> dict[str, object]:
     breakdown = func.breakdown
-    suggestions = suggest_refactors(func.funcdef, breakdown)
+    suggestions = suggest_refactors(func.funcdef, breakdown) if func.score >= suggest_min else []
     return {
         "path": str(func.path),
         "lineno": func.lineno,

{codecoco-3.5.1 → codecoco-3.6.0}/setup.py

@@ -15,11 +15,9 @@ def get_long_description() -> str:
 
 
 setup(
-    # PyPI distribution name. The importable package stays `cognitive_complexity`
-    # (the parent data_pipeline imports it by that name) and the CLI is `cococo`;
-    # both `cognitive_complexity` and `cococo` are already taken on PyPI, so the
-    # distribution is published as `codecoco`. The three names differing is
-    # intentional and documented in the README.
+    # Import package stays `cognitive_complexity` and the CLI is `cococo`; both
+    # names were already taken on PyPI, so the distribution ships as `codecoco`
+    # (the three differ by design — see README).
     name="codecoco",
     description="Library and CLI to compute the cognitive complexity of Python functions",
     classifiers=[

{codecoco-3.5.1 → codecoco-3.6.0}/tests/test_cli.py

@@ -281,12 +281,55 @@ def test_baseline_key_falls_back_to_absolute_when_file_outside_baseline_dir(tmp_
     assert key.startswith("/") and key.endswith("m.py::f")
 
 
+def _listed_quals(out: str) -> list[str]:
+    """Qualnames from the score lines, ignoring inline suggestion lines (`    - ...`)."""
+    return [
+        line.split()[-1] for line in out.splitlines() if line and not line.lstrip().startswith("-")
+    ]
+
+
 def test_main_lists_all_functions_worst_first(tmp_path, capsys):
     # Plain listing mode (no --max): every function is printed, worst first.
     _write(tmp_path, "m.py", NESTED + FLAT)
     assert main([str(tmp_path)]) == 0
-    quals = [line.split()[-1] for line in capsys.readouterr().out.splitlines() if line]
-    assert quals == ["f", "g"]  # f (10) ranks above g (0)
+    assert _listed_quals(capsys.readouterr().out) == ["f", "g"]  # f (10) ranks above g (0)
+
+
+def test_default_listing_shows_inline_suggestions(tmp_path, capsys):
+    # Suggestions are the default output, not a gate-only diagnostic: a plain run
+    # (no --max) prints them inline on stdout for the complex function.
+    _write(tmp_path, "m.py", NESTED + FLAT)
+    assert main([str(tmp_path)]) == 0
+    out = capsys.readouterr().out
+    assert "guard clause" in out.lower()
+    assert "[--fix]" in out
+
+
+def test_default_listing_stays_silent_when_no_suggestion_applies(tmp_path, capsys):
+    # Unlike the gate, listing mode does not print the "no mechanical refactor"
+    # line — a function with no applicable refactor just shows its score.
+    _write(tmp_path, "m.py", NO_SUGGESTION)
+    assert main([str(tmp_path)]) == 0
+    out = capsys.readouterr().out
+    assert "busy" in out
+    assert "no mechanical refactor" not in out
+
+
+def test_suggest_min_filters_inline_suggestions(tmp_path, capsys):
+    # --suggest-min raises the bar for inline suggestions independently of --min:
+    # the function is still listed, but above its score it carries no suggestions.
+    _write(tmp_path, "m.py", NESTED)
+    assert main([str(tmp_path), "--suggest-min", "999"]) == 0
+    out = capsys.readouterr().out
+    assert "f" in _listed_quals(out)
+    assert "guard clause" not in out.lower()
+
+
+def test_suggest_min_filters_json_suggestions(tmp_path, capsys):
+    _write(tmp_path, "m.py", NESTED)
+    assert main([str(tmp_path), "--json", "--suggest-min", "999"]) == 0
+    [func] = json.loads(capsys.readouterr().out)["functions"]
+    assert func["suggestions"] == []
 
 
 # --- refactor suggestions, JSON output, and --fix (added with the refactor feature) ---

codecoco-3.5.1/cognitive_complexity/__init__.py

@@ -1 +0,0 @@
-__version__ = "3.5.1"