python-code-quality 0.3.0__tar.gz → 0.3.1__tar.gz

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: python-code-quality
-Version: 0.3.0
-Summary: Python Code Quality Analysis Tool - feed the results from 11 CQ tools straight into an LLM. Minimal tokens.
+Version: 0.3.1
+Summary: Python Code Quality Analysis Tool - feed the results from 12 CQ tools straight into an LLM. Minimal tokens.
 Author: Chris Kilner
 Author-email: Chris Kilner <chris@rhiza.fr>
 License-Expression: MIT
@@ -35,7 +35,7 @@ Description-Content-Type: text/markdown
 [![Python versions](https://img.shields.io/pypi/pyversions/python-code-quality?)](https://pypi.org/project/python-code-quality/)
 [![License](https://img.shields.io/github/license/rhiza-fr/py-cq)](LICENSE)
 
-Run 11+ code quality tools, aggregate results into one score, and surface the single most critical defect as a focused markdown prompt — ready to pipe to any LLM.
+Run 12 code quality tools, aggregate results into one score, and surface the single most critical defect as a focused markdown prompt — ready to pipe to any LLM.
 
 This can dramatically reduce the amount of noise for LLMs (and humans) and remove the need for them to know about these tools.
 
@@ -81,6 +81,7 @@ When running '-o llm', we run sequentially and exit early at the first error.
 | 9 | radon cc | Cyclomatic complexity |
 | 10 | radon mi | Maintainability index |
 | 11 | radon hal | Halstead volume / bug estimate |
+| 12 | ruff format | Formatting (fraction of files already formatted) |
 
 Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, No pickle risk.
 
@@ -101,7 +102,7 @@ cq check . --exclude demo  # Exclude paths from all tools
 cq check . --workers 1     # Run sequentially if you like things slow
 cq check . --clear-cache   # Clear cached results before running (rarely needed)
 cq check . -o llm --hint   # Append "run cq again to verify" (for human workflows)
-cq config path/to/project/ # Show effective tool configuration
+cq config --path path/to/project/ # Show effective tool configuration
 cq is-fixed <fingerprint>  # Check whether a specific issue has been resolved
 ```
 
@@ -250,14 +251,15 @@ Then invoke it with `/cq-fix` in Claude Code. The `$(...)` embeds the live `cq`
 │ bandit           │    0.56s │                  security │ 1.000   │ OK       │
 │ pytest           │    0.91s │                     tests │ 1.000   │ OK       │
 │ coverage         │    1.26s │                  coverage │ 0.910   │ OK       │
-│ radon cc         │    0.32s │                simplicity │ 0.982   │ OK       │
-│ radon mi         │    0.38s │           maintainability │ 0.869   │ OK       │
-│ radon hal        │    0.30s │             file_bug_free │ 0.928   │ OK       │
-│ radon hal        │          │            file_smallness │ 0.851   │ OK       │
-│ radon hal        │          │        functions_bug_free │ 0.913   │ OK       │
-│ radon hal        │          │       functions_smallness │ 0.724   │ OK       │
 │ vulture          │    0.32s │                 dead_code │ 1.000   │ OK       │
 │ interrogate      │    0.36s │              doc_coverage │ 1.000   │ OK       │
+│ radon-cc         │    0.32s │                simplicity │ 0.982   │ OK       │
+│ radon-mi         │    0.38s │           maintainability │ 0.869   │ OK       │
+│ radon-hal        │    0.30s │             file_bug_free │ 0.928   │ OK       │
+│ radon-hal        │          │            file_smallness │ 0.851   │ OK       │
+│ radon-hal        │          │        functions_bug_free │ 0.913   │ OK       │
+│ radon-hal        │          │       functions_smallness │ 0.724   │ OK       │
+│ ruff-format      │    0.12s │                 formatted │ 1.000   │ OK       │
 │                  │          │                     Score │ 0.965   │          │
 └──────────────────┴──────────┴───────────────────────────┴─────────┴──────────┘
 ```
@@ -339,7 +341,7 @@ warning = 0.9
 error = 0.7
 ```
 
-Tool IDs match the keys in `src/py_cq/config/config.toml`: `compile`, `ruff`, `ty`, `bandit`, `pytest`, `coverage`, `radon-cc`, `radon-mi`, `radon-hal`, `vulture`, `interrogate`.
+Tool IDs match the keys in `src/py_cq/config/config.toml`: `compile`, `ruff`, `ty`, `bandit`, `pytest`, `coverage`, `radon-cc`, `radon-mi`, `radon-hal`, `vulture`, `interrogate`, `ruff-format`.
 
 
 ### Default config
@@ -450,6 +452,15 @@ order = 11
 gate_strict = false
 warning_threshold = 0.35
 error_threshold = 0.3
+
+[python.ruff-format]
+command = "{python} -m ruff format --check --output-format concise --no-cache \"{context_path}\" --exclude .claude --config \"include=['*.py','*.pyi','*.ipynb']\"{exclude}"
+exclude_format = " --exclude {path}"
+parser = "RuffFormatParser"
+order = 12
+gate_strict = false
+warning_threshold = 0.9999
+error_threshold = 0.5
 ```
 
 ## Respect

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/README.md

@@ -6,7 +6,7 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/python-code-quality?)](https://pypi.org/project/python-code-quality/)
 [![License](https://img.shields.io/github/license/rhiza-fr/py-cq)](LICENSE)
 
-Run 11+ code quality tools, aggregate results into one score, and surface the single most critical defect as a focused markdown prompt — ready to pipe to any LLM.
+Run 12 code quality tools, aggregate results into one score, and surface the single most critical defect as a focused markdown prompt — ready to pipe to any LLM.
 
 This can dramatically reduce the amount of noise for LLMs (and humans) and remove the need for them to know about these tools.
 
@@ -52,6 +52,7 @@ When running '-o llm', we run sequentially and exit early at the first error.
 | 9 | radon cc | Cyclomatic complexity |
 | 10 | radon mi | Maintainability index |
 | 11 | radon hal | Halstead volume / bug estimate |
+| 12 | ruff format | Formatting (fraction of files already formatted) |
 
 Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, No pickle risk.
 
@@ -72,7 +73,7 @@ cq check . --exclude demo  # Exclude paths from all tools
 cq check . --workers 1     # Run sequentially if you like things slow
 cq check . --clear-cache   # Clear cached results before running (rarely needed)
 cq check . -o llm --hint   # Append "run cq again to verify" (for human workflows)
-cq config path/to/project/ # Show effective tool configuration
+cq config --path path/to/project/ # Show effective tool configuration
 cq is-fixed <fingerprint>  # Check whether a specific issue has been resolved
 ```
 
@@ -221,14 +222,15 @@ Then invoke it with `/cq-fix` in Claude Code. The `$(...)` embeds the live `cq`
 │ bandit           │    0.56s │                  security │ 1.000   │ OK       │
 │ pytest           │    0.91s │                     tests │ 1.000   │ OK       │
 │ coverage         │    1.26s │                  coverage │ 0.910   │ OK       │
-│ radon cc         │    0.32s │                simplicity │ 0.982   │ OK       │
-│ radon mi         │    0.38s │           maintainability │ 0.869   │ OK       │
-│ radon hal        │    0.30s │             file_bug_free │ 0.928   │ OK       │
-│ radon hal        │          │            file_smallness │ 0.851   │ OK       │
-│ radon hal        │          │        functions_bug_free │ 0.913   │ OK       │
-│ radon hal        │          │       functions_smallness │ 0.724   │ OK       │
 │ vulture          │    0.32s │                 dead_code │ 1.000   │ OK       │
 │ interrogate      │    0.36s │              doc_coverage │ 1.000   │ OK       │
+│ radon-cc         │    0.32s │                simplicity │ 0.982   │ OK       │
+│ radon-mi         │    0.38s │           maintainability │ 0.869   │ OK       │
+│ radon-hal        │    0.30s │             file_bug_free │ 0.928   │ OK       │
+│ radon-hal        │          │            file_smallness │ 0.851   │ OK       │
+│ radon-hal        │          │        functions_bug_free │ 0.913   │ OK       │
+│ radon-hal        │          │       functions_smallness │ 0.724   │ OK       │
+│ ruff-format      │    0.12s │                 formatted │ 1.000   │ OK       │
 │                  │          │                     Score │ 0.965   │          │
 └──────────────────┴──────────┴───────────────────────────┴─────────┴──────────┘
 ```
@@ -310,7 +312,7 @@ warning = 0.9
 error = 0.7
 ```
 
-Tool IDs match the keys in `src/py_cq/config/config.toml`: `compile`, `ruff`, `ty`, `bandit`, `pytest`, `coverage`, `radon-cc`, `radon-mi`, `radon-hal`, `vulture`, `interrogate`.
+Tool IDs match the keys in `src/py_cq/config/config.toml`: `compile`, `ruff`, `ty`, `bandit`, `pytest`, `coverage`, `radon-cc`, `radon-mi`, `radon-hal`, `vulture`, `interrogate`, `ruff-format`.
 
 
 ### Default config
@@ -421,6 +423,15 @@ order = 11
 gate_strict = false
 warning_threshold = 0.35
 error_threshold = 0.3
+
+[python.ruff-format]
+command = "{python} -m ruff format --check --output-format concise --no-cache \"{context_path}\" --exclude .claude --config \"include=['*.py','*.pyi','*.ipynb']\"{exclude}"
+exclude_format = " --exclude {path}"
+parser = "RuffFormatParser"
+order = 12
+gate_strict = false
+warning_threshold = 0.9999
+error_threshold = 0.5
 ```
 
 ## Respect

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "python-code-quality"
-version = "0.3.0"
-description = "Python Code Quality Analysis Tool - feed the results from 11 CQ tools straight into an LLM. Minimal tokens."
+version = "0.3.1"
+description = "Python Code Quality Analysis Tool - feed the results from 12 CQ tools straight into an LLM. Minimal tokens."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "python-code-quality"
-version = "0.3.0"
-description = "Python Code Quality Analysis Tool - feed the results from 11 CQ tools straight into an LLM. Minimal tokens."
+version = "0.3.1"
+description = "Python Code Quality Analysis Tool - feed the results from 12 CQ tools straight into an LLM. Minimal tokens."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/src/py_cq/api.py

@@ -148,7 +148,9 @@ class CQ:
         if clear_cache:
             _cache.clear()
 
-    def raw(self, *, early_exit: bool = False, order: str = "severity") -> list[ToolResult]:
+    def raw(
+        self, *, early_exit: bool = False, order: str = "severity"
+    ) -> list[ToolResult]:
         """Run all tools and return parsed results before aggregation."""
         return run_tools(
             self._registry.values(),
@@ -218,7 +220,7 @@ class CQ:
             )
         if fp.tool not in tool_registry:
             raise ValueError(f"Unknown tool: {fp.tool!r}")
-        
+
         if fp.code and fp.path:
             # Specific issue: target only the affected file for a fast re-check
             file_path = Path(fp.path)
@@ -242,7 +244,11 @@ class CQ:
 
         only_registry = {fp.tool: tool_registry[fp.tool]}
         tool_results = run_tools(
-            only_registry.values(), target, max_workers=1, early_exit=False, excludes=[],
+            only_registry.values(),
+            target,
+            max_workers=1,
+            early_exit=False,
+            excludes=[],
             project_root=str(self.path),
         )
 

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/src/py_cq/cli.py

@@ -107,7 +107,7 @@ def callback(
         help="Show version and dependencies",
     ),
 ) -> None:
-    """Feed the results from 11+ code quality tools to an LLM. Try: cq check . -o llm"""
+    """Feed the results from 12 code quality tools to an LLM. Try: cq check . -o llm"""
     import sys
 
     if isinstance(sys.stdout, io.TextIOWrapper):
@@ -124,7 +124,7 @@ def check(
         OutputMode.TABLE,
         "--output",
         "-o",
-        help="Output mode: table (default), score, json, llm",
+        help="Output mode: table (default), score, json, raw, llm, llm-json",
     ),
     log_level: str = typer.Option(
         "CRITICAL",
@@ -172,7 +172,7 @@ def check(
         help="Issue selection order for -o llm/llm-json: severity (most severe first) or phase (first non-clean phase, in dependency order)",
     ),
 ):
-    """Feed the results from 11+ code quality tools to an LLM. Try: cq check . -o llm"""  # --help
+    """Feed the results from 12 code quality tools to an LLM. Try: cq check . -o llm"""  # --help
     path_obj = Path(path)
     if not path_obj.exists():
         raise typer.BadParameter(f"Path does not exist: {path}")

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/src/py_cq/config/config.toml

@@ -101,3 +101,12 @@ order = 11
 gate_strict = false
 warning_threshold = 0.35
 error_threshold = 0.3
+
+[python.ruff-format]
+command = "{python} -m ruff format --check --output-format concise --no-cache \"{context_path}\" --exclude .claude --config \"include=['*.py','*.pyi','*.ipynb']\"{exclude}"
+exclude_format = " --exclude {path}"
+parser = "RuffFormatParser"
+order = 12
+gate_strict = false
+warning_threshold = 0.9999
+error_threshold = 0.5

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/src/py_cq/execution_engine.py

@@ -328,7 +328,9 @@ def run_tool(
         timestamp=timestamp,
         project_path=project_dir,
     )
-    _cache.set(cache_key, raw_result.to_dict(), expire=5 * 24 * 60 * 60, tag=project_tag)
+    _cache.set(
+        cache_key, raw_result.to_dict(), expire=5 * 24 * 60 * 60, tag=project_tag
+    )
     return raw_result
 
 
@@ -386,7 +388,9 @@ def run_tools(
     t_hash0 = time.perf_counter()
     root = project_root or str(Path(path).resolve())
     shared_hash = get_context_hash(root)
-    log.debug(f"context_hash: {(time.perf_counter() - t_hash0) * 1000:.1f}ms {shared_hash}")
+    log.debug(
+        f"context_hash: {(time.perf_counter() - t_hash0) * 1000:.1f}ms {shared_hash}"
+    )
 
     # Cache keys are content-based, so a changed project naturally produces new
     # keys; stale entries age out via TTL + size_limit (no blanket eviction).
@@ -398,7 +402,9 @@ def run_tools(
     if any(tc.cache_invariant == "ast" for tc in tool_configs):
         t_norm0 = time.perf_counter()
         norm_hash = get_context_hash(root, normalize=True)
-        log.debug(f"context_hash(ast): {(time.perf_counter() - t_norm0) * 1000:.1f}ms {norm_hash}")
+        log.debug(
+            f"context_hash(ast): {(time.perf_counter() - t_norm0) * 1000:.1f}ms {norm_hash}"
+        )
 
     def _hash_for(tool_config: ToolConfig) -> str:
         return norm_hash if tool_config.cache_invariant == "ast" else shared_hash
@@ -410,7 +416,14 @@ def run_tools(
         # Only pass cancel_event when present so patched run_tool stubs in tests
         # (which don't declare the kwarg) keep working for non-cancellable tools.
         extra = {"cancel_event": cancel_event} if cancel_event is not None else {}
-        raw_result = run_tool(tool_config, path, excludes, precomputed_hash=_hash_for(tool_config), project_tag=root, **extra)
+        raw_result = run_tool(
+            tool_config,
+            path,
+            excludes,
+            precomputed_hash=_hash_for(tool_config),
+            project_tag=root,
+            **extra,
+        )
         tr = tool_config.parser_class(tool_config.parser_config).parse(raw_result)
         tr.duration_s = time.perf_counter() - t0
         return tool_config.order, tr
@@ -423,7 +436,9 @@ def run_tools(
             try:
                 prioritized.append(_run_and_parse(tool_config))
             except Exception as exc:  # noqa: BLE001 - a crashing tool must not abort the run
-                log.error(f"{tool_config.name} generated an exception: {exc} {exc.__traceback__}")
+                log.error(
+                    f"{tool_config.name} generated an exception: {exc} {exc.__traceback__}"
+                )
                 n_skipped = n_total - i - 1
                 if n_skipped:
                     remaining = ", ".join(tc.name for tc in sorted_configs[i + 1 :])
@@ -477,7 +492,10 @@ def run_tools(
                 _, dep_tr = dep_future.result()
             except Exception:  # noqa: BLE001 - a crashed dep cancels nothing
                 return
-            if dep_tr.metrics and min(dep_tr.metrics.values()) < dep_config.error_threshold:
+            if (
+                dep_tr.metrics
+                and min(dep_tr.metrics.values()) < dep_config.error_threshold
+            ):
                 log.debug(f"{name}: cancelling because {dep_config.name} failed")
                 ev.set()
 
@@ -485,8 +503,8 @@ def run_tools(
             if tc.name in cancel_events:
                 dep_config = configs_by_name[tc.skip_if]
                 name_to_future[tc.skip_if].add_done_callback(
-                    lambda fut, ev=cancel_events[tc.name], dc=dep_config, nm=tc.name: _cancel_on_dep_failure(
-                        fut, ev, dc, nm
+                    lambda fut, ev=cancel_events[tc.name], dc=dep_config, nm=tc.name: (
+                        _cancel_on_dep_failure(fut, ev, dc, nm)
                     )
                 )
         for future in as_completed(future_to_tool):

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/src/py_cq/localtypes.py

@@ -60,11 +60,11 @@ class ToolConfig:
         default_factory=list
     )  # Top-level dir/file names to omit from {scan_targets}
     skip_for_file: bool = False  # If True, skip when context_path is a single file
-    gate_strict: bool = True  # If False, small regressions above warning_threshold are accepted
-    skip_if: str = ""  # Tool name; if that tool's score is below its error_threshold, skip this tool
-    cache_invariant: str = (
-        ""  # "ast": key the cache on the docstring-stripped AST, ignoring docstrings/comments/format
+    gate_strict: bool = (
+        True  # If False, small regressions above warning_threshold are accepted
     )
+    skip_if: str = ""  # Tool name; if that tool's score is below its error_threshold, skip this tool
+    cache_invariant: str = ""  # "ast": key the cache on the docstring-stripped AST, ignoring docstrings/comments/format
 
 
 @dataclass

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/src/py_cq/parsers/common.py

@@ -47,9 +47,7 @@ def format_source_context(
     error_offset = line - context_start  # 0-based index of the error line in raw_lines
     collected = []
     for i, rline in enumerate(raw_lines):
-        if i > error_offset and (
-            rline.startswith(("def ", "async def ", "class "))
-        ):
+        if i > error_offset and (rline.startswith(("def ", "async def ", "class "))):
             break
         collected.append(f"{context_start + i}: {rline}")
     src = "\n".join(collected)

{python_code_quality-0.3.0 → python_code_quality-0.3.1}/src/py_cq/parsers/interrogateparser.py

@@ -32,7 +32,10 @@ def _format_missing_docstring(file_str: str, line: int, code: str, message: str)
     )
 
     if code == "D100":
-        return base + "\n\nInsert a module-level docstring as the very first statement in the file."
+        return (
+            base
+            + "\n\nInsert a module-level docstring as the very first statement in the file."
+        )
 
     try:
         tree = get_source(file_str).tree
@@ -74,6 +77,7 @@ def _format_missing_docstring(file_str: str, line: int, code: str, message: str)
 
     return base + "\n\nInsert a docstring as the first statement in the body."
 
+
 _ROW_RE = re.compile(
     r"^\|\s+(.+?)\s+\|\s+(\d+)\s+\|\s+(\d+)\s+\|\s+\d+\s+\|\s+(\d+(?:\.\d+)?)%\s*\|"
 )
@@ -85,7 +89,9 @@ def _load_interrogate_cfg(context_path: str) -> dict:
     """Read [tool.interrogate] from the nearest pyproject.toml."""
     p = Path(context_path).resolve()
     for candidate in [p, *p.parents]:
-        pyproject = (candidate if candidate.is_dir() else candidate.parent) / "pyproject.toml"
+        pyproject = (
+            candidate if candidate.is_dir() else candidate.parent
+        ) / "pyproject.toml"
         if pyproject.exists():
             try:
                 data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
@@ -109,7 +115,9 @@ def _skip_node(name: str, cfg: dict) -> bool:
     return bool(is_semiprivate and cfg.get("ignore-semiprivate"))
 
 
-def _missing_docstrings(file_path: Path, cfg: dict | None = None) -> list[tuple[int, str, str]]:
+def _missing_docstrings(
+    file_path: Path, cfg: dict | None = None
+) -> list[tuple[int, str, str]]:
     """Return (line, kind, source_line) for each node missing a docstring.
 
     kind is 'module', 'def', or 'class'. source_line is the verbatim text of

python_code_quality-0.3.1/src/py_cq/parsers/ruffformatparser.py

@@ -0,0 +1,62 @@
+"""Parses output from ruff format --check into a standardized ToolResult.
+
+The output is one line per unformatted file. ruff >= 0.16 honours
+``--output-format concise``::
+
+    <file>:<line>:<col>: unformatted: File would be reformatted
+
+while older versions ignore it (it needs preview mode) and print::
+
+    Would reformat: <file>
+
+Either is followed by a summary line such as
+``2 files would be reformatted, 30 files already formatted`` or
+``32 files already formatted``.
+
+The score is the fraction of checked files that are already formatted,
+taken from the summary so it stays correct if the per-file format changes."""
+
+import re
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import extract_first_issue
+
+_FILE_RE = re.compile(r"^(?:Would reformat: (.+)|(.+):\d+:\d+: unformatted: .*)$")
+_FORMATTED_RE = re.compile(r"(\d+) files? already formatted")
+_UNFORMATTED_RE = re.compile(r"(\d+) files? would be reformatted")
+
+
+class RuffFormatParser(AbstractParser):
+    """Parses ``ruff format --check --output-format concise`` output into a ToolResult."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Collect unformatted files and score the fraction already formatted."""
+        stdout = raw_result.stdout or ""
+        # One issue per file, with no line: the line ruff reports is the first
+        # diff hunk, which would make the fingerprint unstable across edits.
+        files: dict[str, list] = {}
+        for line in stdout.splitlines():
+            m = _FILE_RE.match(line)
+            if m:
+                files[(m.group(1) or m.group(2)).replace("\\", "/")] = [{}]
+        m = _FORMATTED_RE.search(stdout)
+        formatted = int(m.group(1)) if m else 0
+        m = _UNFORMATTED_RE.search(stdout)
+        unformatted = max(int(m.group(1)) if m else 0, len(files))
+        total = formatted + unformatted
+        score = formatted / total if total else 1.0
+        return ToolResult(raw=raw_result, metrics={"formatted": score}, details=files)
+
+    def format_llm_message(
+        self, tr: ToolResult, *, context_lines: int = 15, limit: int = 1
+    ) -> str:
+        """Ask for the formatter to be run rather than a hand edit."""
+        result = extract_first_issue(tr.details)
+        if result is None:
+            return "ruff format reported issues (no details available)"
+        file, _ = result
+        return (
+            f"{file} - **not formatted**. Run the formatter, do not edit by hand:\n\n"
+            f"```bash\nruff format {file}\n```\n\n"
+            "Other files may also need formatting; `ruff format .` fixes them all."
+        )