python-code-quality 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

py_cq/cli.py

@@ -23,12 +23,11 @@ from rich.console import Console
 from rich.logging import RichHandler
 from rich.table import Table
 
-from py_cq.config import DEFAULT_STORAGE_FILE, load_user_config
+from py_cq.config import load_user_config
 from py_cq.execution_engine import _cache as tool_cache
 from py_cq.execution_engine import run_tools
 from py_cq.localtypes import CombinedToolResults, ToolConfig
 from py_cq.metric_aggregator import aggregate_metrics
-from py_cq.storage import save_result
 from py_cq.tool_registry import tool_registry
 
 logging.basicConfig(
@@ -44,6 +43,8 @@ app = typer.Typer(
         "  cq check .          # full table with all metrics (default)\n\n"
         "  cq check . -o llm   # top defect as markdown (primary LLM workflow)\n\n"
         "  cq check . -o score # numeric score only\n\n"
+        "  cq check . -o json  # parsed metrics as json\n\n"
+        "  cq check . -o raw   # unprocessed tool output as json\n\n"
         "  cq config .         # show effective tool configuration"
     ),
 )
@@ -74,11 +75,12 @@ class OutputMode(str, Enum):
     SCORE = "score"
     JSON = "json"
     LLM = "llm"
+    RAW = "raw"
 
 
 @app.callback()
 def callback():
-    """CQ - Code Quality Analysis Tool."""
+    """Feed the results from 11+ code quality tools to an LLM. Try: cq check . -o llm"""
 console = Console()
 
 
@@ -93,11 +95,6 @@ def check(
         "--log-level",
         help="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
     ),
-    out_file: str = typer.Option(
-        DEFAULT_STORAGE_FILE,
-        "--out-file",
-        help="File path to save results in table mode",
-    ),
     clear_cache: bool = typer.Option(
         False, "--clear-cache", help="Clear cached tool results before running"
     ),
@@ -105,7 +102,7 @@ def check(
         0, "--workers", help="Max parallel workers (default: one per tool, use 1 for sequential)"
     ),
 ):
-    """Run static analysis on a Python file or project directory."""
+    """Feed the results from 11+ 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}")
@@ -119,20 +116,21 @@ def check(
     effective_registry = _apply_user_config(tool_registry, load_user_config(path_obj))
     if clear_cache:
         tool_cache.clear()
-    tool_results = run_tools(effective_registry.values(), path, workers)
-    for tr in tool_results:
-        log.debug(json.dumps(tr.to_dict(), indent=2))
+    tool_results = run_tools(effective_registry.values(), path, workers, early_exit=(output == OutputMode.LLM))
+    # for tr in tool_results:
+    #     log.debug(json.dumps(tr.to_dict(), indent=2))
     combined_metrics = aggregate_metrics(path=path, metrics=tool_results)
     if output == OutputMode.SCORE:
         console.print(combined_metrics.score)
     elif output == OutputMode.JSON:
-        console.print(json.dumps(combined_metrics.to_dict(), indent=2))
+        console.print(json.dumps([tr.to_dict() for tr in tool_results], indent=2))
+    elif output == OutputMode.RAW:
+        console.print(json.dumps([tr.raw.to_dict() for tr in tool_results], indent=2))
     elif output == OutputMode.LLM:
-        log.setLevel("CRITICAL")
+        # log.setLevel("CRITICAL")
         from py_cq.llm_formatter import format_for_llm
         console.print(format_for_llm(effective_registry, combined_metrics))
     else:
-        save_result(combined_tool_results=combined_metrics, file_name=out_file)
         console.print(format_as_table(combined_metrics, effective_registry))
 
 
@@ -169,18 +167,18 @@ def config(
 
     table = Table()
     table.add_column("Tool", style="cyan")
-    table.add_column("Priority", justify="right")
+    table.add_column("Order", justify="right")
     table.add_column("Warning", justify="right")
     table.add_column("Error", justify="right")
     table.add_column("Status", justify="center")
 
-    for tool_id in sorted(tool_registry, key=lambda t: tool_registry[t].priority):
+    for tool_id in sorted(tool_registry, key=lambda t: tool_registry[t].order):
         tc = effective_registry.get(tool_id, tool_registry[tool_id])
         is_disabled = tool_id in disabled_ids
         status = "[red]disabled[/red]" if is_disabled else "[green]enabled[/green]"
         table.add_row(
             tc.name,
-            str(tc.priority),
+            str(tc.order),
             f"{tc.warning_threshold:.2f}",
             f"{tc.error_threshold:.2f}",
             status,

py_cq/config/__init__.py

@@ -1,10 +1,8 @@
-"""Default storage path and user config loader."""
+"""User config loader."""
 
 import tomllib
 from pathlib import Path
 
-DEFAULT_STORAGE_FILE = ".cq.json"
-
 
 def load_user_config(project_path: Path) -> dict:
     """Read [tool.cq] from pyproject.toml at project_path, if present.

py_cq/config/tools.yaml

@@ -4,15 +4,15 @@ tools:
     name: "compile"
     command: "{python} -m compileall -r 10 -j 8 {context_path} -x .*venv"
     parser: "CompileParser"
-    priority: 1
+    order: 1
     warning_threshold: 0.9999
     error_threshold: 0.9999
 
   bandit:
     name: "bandit"
-    command: "{python} -m bandit -r {context_path} -f json -q -s B101 --severity-level medium --exclude {context_dir}/.venv,{context_dir}/tests"
+    command: "{python} -m bandit -r {context_path} -f json -q -s B101 --severity-level medium --exclude {input_path_posix}/.venv,{input_path_posix}/tests"
     parser: "BanditParser"
-    priority: 2
+    order: 2
     warning_threshold: 0.9999
     error_threshold: 0.8
 
@@ -20,7 +20,7 @@ tools:
     name: "ruff"
     command: "{python} -m ruff check --output-format concise --no-cache {context_path}"
     parser: "RuffParser"
-    priority: 3
+    order: 3
     warning_threshold: 0.9999
     error_threshold: 0.9
 
@@ -28,7 +28,7 @@ tools:
     name: "ty"
     command: "{python} -m ty check --output-format concise --color never {context_path}"
     parser: "TyParser"
-    priority: 4
+    order: 4
     warning_threshold: 0.9999
     error_threshold: 0.8
     run_in_target_env: true
@@ -39,16 +39,16 @@ tools:
     name: "pytest"
     command: "{python} -m pytest -v {context_path}"
     parser: "PytestParser"
-    priority: 5
+    order: 5
     warning_threshold: 0.7
     error_threshold: 0.5
     run_in_target_env: true
 
   coverage:
     name: "coverage"
-    command: "{python} -m coverage run -m pytest {context_path} && {python} -m coverage report"
+    command: "{python} -m coverage run --omit=*/tests/*,*/test_*.py -m pytest {context_path} && {python} -m coverage report --omit=*/tests/*,*/test_*.py"
     parser: "CoverageParser"
-    priority: 6
+    order: 6
     warning_threshold: 0.9
     error_threshold: 0.5
     run_in_target_env: true
@@ -60,7 +60,7 @@ tools:
     name: "radon cc"
     command: "{python} -m radon cc --json {context_path}"
     parser: "ComplexityParser"
-    priority: 7
+    order: 7
     warning_threshold: 0.6
     error_threshold: 0.4
 
@@ -68,7 +68,7 @@ tools:
     name: "radon mi"
     command: "{python} -m radon mi -s --json {context_path}"
     parser: "MaintainabilityParser"
-    priority: 8
+    order: 8
     warning_threshold: 0.6
     error_threshold: 0.4
 
@@ -76,7 +76,7 @@ tools:
     name: "radon hal"
     command: "{python} -m radon hal -f --json {context_path}"
     parser: "HalsteadParser"
-    priority: 9
+    order: 9
     warning_threshold: 0.5
     error_threshold: 0.3
 
@@ -84,7 +84,7 @@ tools:
     name: "vulture"
     command: "{python} -m vulture {context_path} --min-confidence 80 --exclude .venv,dist,.*_cache,docs,.git"
     parser: "VultureParser"
-    priority: 10
+    order: 10
     warning_threshold: 0.9999
     error_threshold: 0.8
 
@@ -92,6 +92,6 @@ tools:
     name: "interrogate"
     command: "{python} -m interrogate {context_path} -v --fail-under 0"
     parser: "InterrogateParser"
-    priority: 11
+    order: 11
     warning_threshold: 0.8
     error_threshold: 0.3

py_cq/execution_engine.py

@@ -20,16 +20,16 @@ import time
 from collections.abc import Collection
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
-from typing import cast
+from typing import Any, cast
 
-import diskcache
+from diskcache import Cache, JSONDisk
 
 from py_cq.context_hash import get_context_hash
 from py_cq.localtypes import RawResult, ToolConfig, ToolResult
 
 log = logging.getLogger("cq")
 
-_cache = diskcache.Cache(Path.home() / ".cache" / "cq")
+_cache = Cache(Path.home() / ".cache" / "cq", size_limit=100 * 1024 * 1024, disk=JSONDisk)
 
 
 def _find_project_root(path: Path) -> Path | None:
@@ -75,12 +75,12 @@ def run_tool(tool_config: ToolConfig, context_path: str) -> RawResult:
             with_flags = " ".join(f"--with {dep}" for dep in tool_config.extra_deps)
             python = f'"{uv}" run --directory "{abs_dir}" {with_flags}'.rstrip()
     abs_context_path = str(Path(context_path).resolve())
-    context_dir = Path(context_path).as_posix().rstrip("/")
-    command = tool_config.command.format(context_path=path, abs_context_path=abs_context_path, context_dir=context_dir, python=python)
+    input_path_posix = Path(context_path).as_posix().rstrip("/")
+    command = tool_config.command.format(context_path=path, abs_context_path=abs_context_path, input_path_posix=input_path_posix, python=python)
     cache_key = f"{command}:{get_context_hash(context_path)}"
     if cache_key in _cache:
         log.info(f"Cache hit: {command}")
-        return cast(RawResult, _cache[cache_key])
+        return RawResult(**cast(dict[str, Any], _cache[cache_key]))
     log.info(f"Running: {command}")
     result = subprocess.run(command, capture_output=True, text=True, shell=True) # nosec
     timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
@@ -92,11 +92,11 @@ def run_tool(tool_config: ToolConfig, context_path: str) -> RawResult:
         return_code=result.returncode,
         timestamp=timestamp,
     )
-    _cache[cache_key] = raw_result
+    _cache.set(cache_key, raw_result.to_dict(), expire=5 * 24 * 60 * 60)
     return raw_result
 
 
-def run_tools(tool_configs: Collection[ToolConfig], path: str, max_workers: int = 0) -> list[ToolResult]:
+def run_tools(tool_configs: Collection[ToolConfig], path: str, max_workers: int = 0, early_exit: bool = False) -> list[ToolResult]:
     """Run multiple tools and return their parsed results.
 
     Runs each tool specified in *tool_configs* on the file or directory at
@@ -141,12 +141,24 @@ def run_tools(tool_configs: Collection[ToolConfig], path: str, max_workers: int
         raw_result = run_tool(tool_config, path)
         tr = tool_config.parser_class().parse(raw_result)
         tr.duration_s = time.perf_counter() - t0
-        return tool_config.priority, tr
+        return tool_config.order, tr
 
     if not tool_configs:
         return []
     t_start = time.perf_counter()
     prioritized: list[tuple[int, ToolResult]] = []
+    if early_exit:
+        for tool_config in sorted(tool_configs, key=lambda tc: tc.order):
+            try:
+                prioritized.append(_run_and_parse(tool_config))
+            except Exception as exc:
+                log.error(f"{tool_config.name} generated an exception: {exc}")
+                break
+            _, tr = prioritized[-1]
+            if tr.metrics and min(tr.metrics.values()) < tool_config.error_threshold:
+                break
+        log.info(f"run_tools elapsed: {time.perf_counter() - t_start:.2f}s")
+        return [tr for _, tr in sorted(prioritized)]
     with ThreadPoolExecutor(max_workers=max_workers or len(tool_configs)) as executor:
         future_to_tool = {
             executor.submit(_run_and_parse, tool_config): tool_config

py_cq/llm_formatter.py

@@ -29,7 +29,7 @@ def format_for_llm(
         ],
         key=lambda tr: (
             _severity(min(tr.metrics.values()), by_name[tr.raw.tool_name]),
-            by_name[tr.raw.tool_name].priority,
+            by_name[tr.raw.tool_name].order,
             min(tr.metrics.values()),
         ),
     )

py_cq/localtypes.py

@@ -10,13 +10,13 @@ from typing import Any
 
 @dataclass
 class ToolConfig:
-    """Represents the configuration for an analysis tool, including its name, command, parser class, context path, priority, and thresholds for warnings and errors."""
+    """Represents the configuration for an analysis tool, including its name, command, parser class, context path, order, and thresholds for warnings and errors."""
 
     name: str  # e.g., "pytest", "coverage", "pydocstyle"
     command: str  # The command to execute (can include placeholders)
     parser_class: Callable  # Name of the parser class to use
     context_path: str = ""  # Path to project or file
-    priority: int = 5  # 1=critical (compilation), 5=low (style)
+    order: int = 5  # 1=first (compilation), 11=last (style)
     warning_threshold: float = 0.7  # Yellow warning if below this
     error_threshold: float = 0.5  # Red error if below this
     run_in_target_env: bool = False  # If True, run in target project's env via uv
@@ -73,11 +73,11 @@ class ToolResult:
             self.metrics = {}
 
     def to_dict(self) -> dict:
-        """Returns a dictionary containing the metrics, details, and the raw data serialized via its own `to_dict` method."""
+        """Returns a dictionary containing the tool name, metrics, details, and duration."""
         return {
+            "tool_name": self.raw.tool_name,
             "metrics": self.metrics,
             "details": self.details,
-            "raw": self.raw.to_dict(),
             "duration_s": self.duration_s,
         }
 

py_cq/parsers/banditparser.py

@@ -9,7 +9,7 @@ logistic-variant score stored under the ``security`` metric key.
 import json
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import score_logistic_variant
+from py_cq.parsers.common import format_source_context, score_logistic_variant
 
 _SEVERITY_WEIGHT = {"HIGH": 5, "MEDIUM": 2, "LOW": 1}
 
@@ -51,4 +51,4 @@ class BanditParser(AbstractParser):
         code = issue.get("code", "")
         severity = issue.get("severity", "")
         message = issue.get("message", "")
-        return f"`{file}:{line}` — **{code}** [{severity}]: {message}"
+        return f"`{file}:{line}` — **{code}** [{severity}]: {message}{format_source_context(file, line)}"

py_cq/parsers/common.py

@@ -25,6 +25,18 @@ def read_source_lines(file_path: str, line: int, count: int = 5) -> str:
         return ""
 
 
+def format_source_context(file: str, line: int | str, context: int = 3, count: int = 8) -> str:
+    """Return a fenced python code block for the source around `line`, or '' if unavailable."""
+    if not isinstance(line, int):
+        return ""
+    context_start = max(1, line - context)
+    raw_lines = read_source_lines(file, context_start, count=count).splitlines()
+    if not raw_lines:
+        return ""
+    src = "\n".join(f"{context_start + i}: {rline}" for i, rline in enumerate(raw_lines))
+    return f"\n```python\n{src}\n```"
+
+
 def inv_normalize(value: float, max_value: float) -> float:
     """Returns the inverse normalized value of `value` relative to `max_value`."""
     return (max_value - min(value, max_value)) / max_value

py_cq/parsers/compileparser.py

@@ -6,7 +6,7 @@ compile score, and providing concise help messages for any failures."""
 import logging
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import read_source_lines, score_logistic_variant
+from py_cq.parsers.common import format_source_context, score_logistic_variant
 
 log = logging.getLogger("cq")
 
@@ -124,11 +124,5 @@ class CompileParser(AbstractParser):
         line = info.get("line", "?")
         typ = info.get("type", "Error")
         help_msg = info.get("help", "")
-        if isinstance(line, int):
-            context_start = max(1, line - 3)
-            raw_lines = read_source_lines(file, context_start, count=8).splitlines()
-            src = "\n".join(f"{context_start + i}: {rline}" for i, rline in enumerate(raw_lines)) if raw_lines else info.get("src", "")
-        else:
-            src = info.get("src", "")
-        code_block = f"\n```python\n{src}\n```" if src else ""
+        code_block = format_source_context(file, line) or (f"\n```python\n{info['src']}\n```" if info.get("src") else "")
         return f"`{file}:{line}` — **{typ}**: {help_msg}{code_block}"

py_cq/parsers/halsteadparser.py

@@ -62,7 +62,7 @@ class HalsteadParser(AbstractParser):
         MAX_FILE_BUGS = 1
         MAX_FILE_VOLUME = 2000
         MAX_FUNCTION_BUGS = 0.2
-        MAX_FUNCTION_VOLUME = 300
+        MAX_FUNCTION_VOLUME = 600
         min_file_nb = 1.0
         min_file_sm = 1.0
         min_function_nb = 1.0

py_cq/parsers/pytestparser.py

@@ -67,6 +67,14 @@ class PytestParser(AbstractParser):
                     num_tests += 1
                     if test_status == "PASSED":
                         passed_tests += 1
+            if num_tests == 0:
+                # No individual test lines found (e.g. non-verbose output);
+                # fall back to parsing the pytest summary line.
+                summary = re.search(r"(\d+) passed(?:.*?(\d+) failed)?", raw_result.stdout)
+                if summary:
+                    passed_tests = int(summary.group(1))
+                    failed_tests = int(summary.group(2)) if summary.group(2) else 0
+                    num_tests = passed_tests + failed_tests
             tr.metrics["tests"] = passed_tests / num_tests if num_tests else 0
             tr.details = tests_found
         return tr

py_cq/parsers/ruffparser.py

@@ -13,7 +13,7 @@ followed by a summary line ``Found N error.`` or ``All checks passed!``."""
 import re
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import read_source_lines, score_logistic_variant
+from py_cq.parsers.common import format_source_context, score_logistic_variant
 
 _DIAG_RE = re.compile(r"^(.+):(\d+):(\d+): ([A-Z]\d+) (.+)$")
 
@@ -54,8 +54,4 @@ class RuffParser(AbstractParser):
         line = issue.get("line", "?")
         code = issue.get("code", "")
         message = issue.get("message", "")
-        context_start = max(1, line - 3) if isinstance(line, int) else line
-        raw_lines = read_source_lines(file, context_start, count=8).splitlines() if isinstance(line, int) else []
-        src = "\n".join(f"{context_start + i}: {rline}" for i, rline in enumerate(raw_lines)) if raw_lines else ""
-        code_block = f"\n```python\n{src}\n```" if src else ""
-        return f"`{file}:{line}` — **{code}**: {message}{code_block}"
+        return f"`{file}:{line}` — **{code}**: {message}{format_source_context(file, line)}"

py_cq/parsers/typarser.py

@@ -14,7 +14,7 @@ Errors count more heavily than warnings toward the score."""
 import re
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import read_source_lines, score_logistic_variant
+from py_cq.parsers.common import format_source_context, score_logistic_variant
 
 _DIAG_RE = re.compile(r"^(.+):(\d+):\d+:\s+(error|warning)\[([^\]]+)\] (.+)$")
 
@@ -58,8 +58,4 @@ class TyParser(AbstractParser):
         line = issue.get("line", "?")
         code = issue.get("code", "")
         message = issue.get("message", "")
-        context_start = max(1, line - 3) if isinstance(line, int) else line
-        raw_lines = read_source_lines(file, context_start, count=8).splitlines() if isinstance(line, int) else []
-        src = "\n".join(f"{context_start + i}: {rline}" for i, rline in enumerate(raw_lines)) if raw_lines else ""
-        code_block = f"\n```python\n{src}\n```" if src else ""
-        return f"`{file}:{line}` — **{code}**: {message}{code_block}"
+        return f"`{file}:{line}` — **{code}**: {message}{format_source_context(file, line)}"

py_cq/parsers/vultureparser.py

@@ -12,7 +12,7 @@ score stored under the ``dead_code`` metric key.
 import re
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import score_logistic_variant
+from py_cq.parsers.common import format_source_context, score_logistic_variant
 
 _LINE_RE = re.compile(r"^(.+):(\d+): (unused \S+) '(.+)' \((\d+)% confidence\)$")
 
@@ -45,4 +45,4 @@ class VultureParser(AbstractParser):
         kind = issue.get("type", "unused")
         name = issue.get("name", "")
         confidence = issue.get("confidence", "?")
-        return f"`{file}:{line}` — **{kind}** `{name}` ({confidence}% confidence)"
+        return f"`{file}:{line}` — **{kind}** `{name}` ({confidence}% confidence){format_source_context(file, line)}"

py_cq/tool_registry.py

@@ -24,7 +24,7 @@ def load_tool_configs() -> dict[str, ToolConfig]:
             name=tool_data["name"],
             command=tool_data["command"],
             parser_class=parser_class,
-            priority=tool_data["priority"],
+            order=tool_data["order"],
             warning_threshold=tool_data["warning_threshold"],
             error_threshold=tool_data["error_threshold"],
             run_in_target_env=tool_data.get("run_in_target_env", False),

{python_code_quality-0.1.6.dist-info → python_code_quality-0.1.8.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: python-code-quality
-Version: 0.1.6
-Summary: Python Code Quality Analysis Tool - feed the results from 11 CQ CQ straight into an LLM.
+Version: 0.1.8
+Summary: Python Code Quality Analysis Tool - feed the results from 11 CQ tools straight into an LLM. Minimal tokens.
 Project-URL: Homepage, https://github.com/rhiza-fr/py-cq
 Project-URL: Repository, https://github.com/rhiza-fr/py-cq
 Author-email: Chris Kilner <chris@rhiza.fr>
@@ -26,20 +26,50 @@ Description-Content-Type: text/markdown
 
 # CQ - Python Code Quality Analysis Tool
 
-Python Code Quality Analysis Tool - feed the results from 11 CQ tools straight into an LLM. The primary workflow is:
+Feed the results from 11+ code quality tools to an LLM. Minimal tokens.
+
+The primary workflow is:
 
 ```bash
-cq check -o llm   # get the single most critical defect as markdown
+# get the single most critical defect as markdown
+cq check . -o llm
 ```
+Selects the single most critical defect using this priority order:
+
+1. **Severity** — tools with score below `error_threshold` come before those only below `warning_threshold`
+2. **Order** — among tools at the same severity, lower-order tools win (compile before lint before style)
+3. **Score** — among ties, the lower score wins
 
-Feed that output to an LLM, apply the fix, repeat until the score is clean.
+The code context is expanded if available.
+```md
+`data/problems/travelling_salesman/ts_bad.py:21` — **F841**: Local variable `unused_variable` is assigned to but never used
+
+18:     min_dist = float("inf")
+19:     nearest_city = None
+20:     for city in cities:
+21:         unused_variable = 67
+22:         dist = calc_dist(current_city, city)
+23:         if dist < min_dist:
+24:             min_dist = dist
+25:             nearest_city = city
+
+Please fix only this issue. After fixing, run `cq check . -o llm` to verify.
+```
+Feed to an LLM with edit tools and repeat until there are no issues, e.g.
+
+```python
+cq check . -o llm | claude -p "fix this"
+# or
+cq check . -o llm | ollama gpt-oss:20b "Explain how to fix this"
+```
 
 ## Install
 
 ```bash
+# install the `cq` command line tool from PyPi
 uv tool install python-code-quality
 
-# or
+# or, clone it then install 
 git pull https://github.com/rhiza-fr/py-cq.git
 cd py-cq
 uv tool install .
@@ -47,9 +77,9 @@ uv tool install .
 
 ## Tools
 
-CQ runs these tools in *parallel*:
+These tools are run in **parallel** except when looking for the first error in -o llm mode:
 
-| Priority | Tool | Measures |
+| Order | Tool | Measures |
 |----------|------|----------|
 | 1 | compileall | Syntax errors |
 | 2 | bandit | Security vulnerabilities |
@@ -63,40 +93,24 @@ CQ runs these tools in *parallel*:
 | 10 | vulture | Dead code |
 | 11 | interrogate | Docstring coverage |
 
-## Usage
-
-```bash
-# LLM workflow: get the top defect as markdown (primary use case)
-cq check -o llm
-
-# Rich table with all metrics (default, also saves .cq.json)
-cq check
+Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, No pickle
 
-# Numeric score only — useful in CI or scripts
-cq check -o score
 
-# Full JSON output
-cq check -o json
-
-# Explicit path (defaults to current directory)
-cq check path/to/project/
-cq check path/to/file.py
-
-# Run sequentially (1 worker) instead of in parallel
-cq check --workers 1
-
-# Clear cached results before running
-cq check --clear-cache
-
-# Save table output to a custom file
-cq check --out-file custom_results.json
+## Usage
 
-# Show effective tool configuration (thresholds, enabled/disabled status)
-cq config
-cq config path/to/project/
+```bash
+cq check .                 # Table overview of scores for humans
+cq check -o llm            # Top defect as markdown for LLMs
+cq check . -o score        # Numeric score only for CI
+cq check . -o json         # Detailed parsed JSON output for jq
+cq check . -o raw          # Raw tool output for debug
+cq check path/to/file.py   # Just one file (skips pytest and coverage)
+cq check . --workers 1     # Run sequentially if you like things slow
+cq check . --clear-cache   # Clear cached results before running (rarely needed)
+cq config path/to/project/ # Show effective tool configuration
 ```
 
-## Output
+## Table output
 
 ```bash
 > cq check .
@@ -123,6 +137,8 @@ cq config path/to/project/
 │                  │          │                     Score │ 0.965   │          │
 └──────────────────┴──────────┴───────────────────────────┴─────────┴──────────┘
 ```
+
+## Single score output
 ```bash
 > cq check . -o score
 ```
@@ -130,23 +146,42 @@ cq config path/to/project/
 0.9662730667181059 # this is designed to approach but not reach 1.0
 ```
 
+## Json output
 ```bash
-> cq check . -o llm
+> cq check . -o json
 ```
 
-```md
-`data/problems/travelling_salesman/ts_bad.py:21` — **F841**: Local variable `unused_variable` is assigned to but never used
+```json
+[
+  {
+    "tool_name": "compile",
+    "metrics": {
+      "compile": 1.0
+    },
+    "details": {},
+    "duration_s": 0.05611889995634556
+  }
+  ...
+]
+```
 
-18:     min_dist = float("inf")
-19:     nearest_city = None
-20:     for city in cities:
-21:         unused_variable = 67
-22:         dist = calc_dist(current_city, city)
-23:         if dist < min_dist:
-24:             min_dist = dist
-25:             nearest_city = city
+## Raw output
+```bash
+> cq check -o raw
+```
 
-Please fix only this issue. After fixing, run `cq check . -o llm` to verify.
+```json
+[
+  {
+    "tool_name": "compile",
+    "command": "D:\\ai\\py-cq\\.venv\\Scripts\\python.exe -m compileall -r 10 -j 8 . -x .*venv",
+    "stdout": "",
+    "stderr": "",
+    "return_code": 0,
+    "timestamp": "2026-02-20 10:01:22"
+  }
+  ...
+]
 ```
 
 ## Configuration
@@ -166,14 +201,111 @@ error = 0.7
 
 Tool IDs match the keys in `config/tools.yaml`: `compilation`, `bandit`, `ruff`, `ty`, `pytest`, `coverage`, `complexity`, `maintainability`, `halstead`, `vulture`, `interrogate`.
 
-## LLM workflow
 
-`-o llm` selects the single worst-scoring tool and formats its top defect as
-concise markdown. The LLM fixes it, you re-run `cq check -o llm`, and repeat
-until all tools are green. Priority order ensures the most critical category
-(security, type errors, failing tests) is fixed before cosmetic ones.
+### Default config
+
+```yaml
+tools:
+
+  compilation:
+    name: "compile"
+    command: "{python} -m compileall -r 10 -j 8 {context_path} -x .*venv"
+    parser: "CompileParser"
+    order: 1
+    warning_threshold: 0.9999
+    error_threshold: 0.9999
+
+  bandit:
+    name: "bandit"
+    command: "{python} -m bandit -r {context_path} -f json -q -s B101 --severity-level medium --exclude {input_path_posix}/.venv,{input_path_posix}/tests"
+    parser: "BanditParser"
+    order: 2
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+
+  ruff:
+    name: "ruff"
+    command: "{python} -m ruff check --output-format concise --no-cache {context_path}"
+    parser: "RuffParser"
+    order: 3
+    warning_threshold: 0.9999
+    error_threshold: 0.9
+
+  ty:
+    name: "ty"
+    command: "{python} -m ty check --output-format concise --color never {context_path}"
+    parser: "TyParser"
+    order: 4
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+    run_in_target_env: true
+    extra_deps:
+      - ty
+
+  pytest:
+    name: "pytest"
+    command: "{python} -m pytest -v {context_path}"
+    parser: "PytestParser"
+    order: 5
+    warning_threshold: 0.7
+    error_threshold: 0.5
+    run_in_target_env: true
+
+  coverage:
+    name: "coverage"
+    command: "{python} -m coverage run --omit=*/tests/*,*/test_*.py -m pytest {context_path} && {python} -m coverage report --omit=*/tests/*,*/test_*.py"
+    parser: "CoverageParser"
+    order: 6
+    warning_threshold: 0.9
+    error_threshold: 0.5
+    run_in_target_env: true
+    extra_deps:
+      - coverage
+      - pytest
+
+  complexity:
+    name: "radon cc"
+    command: "{python} -m radon cc --json {context_path}"
+    parser: "ComplexityParser"
+    order: 7
+    warning_threshold: 0.6
+    error_threshold: 0.4
+
+  maintainability:
+    name: "radon mi"
+    command: "{python} -m radon mi -s --json {context_path}"
+    parser: "MaintainabilityParser"
+    order: 8
+    warning_threshold: 0.6
+    error_threshold: 0.4
+
+  halstead:
+    name: "radon hal"
+    command: "{python} -m radon hal -f --json {context_path}"
+    parser: "HalsteadParser"
+    order: 9
+    warning_threshold: 0.5
+    error_threshold: 0.3
+
+  vulture:
+    name: "vulture"
+    command: "{python} -m vulture {context_path} --min-confidence 80 --exclude .venv,dist,.*_cache,docs,.git"
+    parser: "VultureParser"
+    order: 10
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+
+  interrogate:
+    name: "interrogate"
+    command: "{python} -m interrogate {context_path} -v --fail-under 0"
+    parser: "InterrogateParser"
+    order: 11
+    warning_threshold: 0.8
+    error_threshold: 0.3
 
-## Tools
+```
+
+## Respect
 
 Many thanks to all the wonderful maintainers of :
 
@@ -186,3 +318,5 @@ Many thanks to all the wonderful maintainers of :
 - [radon](https://github.com/rubik/radon)
 - [vulture](https://github.com/jendrikseipp/vulture)
 - [interrogate](https://github.com/econchick/interrogate)
+- [diskcache](https://github.com/grantjenks/python-diskcache)
+- [typer](https://github.com/fastapi/typer)

python_code_quality-0.1.8.dist-info/RECORD

@@ -0,0 +1,30 @@
+py_cq/__init__.py,sha256=rS7kf1RU1zZskvJlkbZaMqEpdRYPspwDPAFbxzF3tXg,373
+py_cq/cli.py,sha256=9rNdLdU2mcZVz3qdkczO4Rs_PU0-brZMmj5wJfv-Jcs,8688
+py_cq/context_hash.py,sha256=h-i7Rhd7AUfLv9SkQvE79bjJvTsm_ZwoVwSmUKXWmfM,2977
+py_cq/execution_engine.py,sha256=Q7Z8iibkE_E9VfkbUdnI_g5wA8GdwDbnJI4Mex-V8mE,7416
+py_cq/llm_formatter.py,sha256=EdUMhvsnPLplSSUKDknMHiaLdKsd9B6aH-tTdpxukdY,1574
+py_cq/localtypes.py,sha256=_PAx-F0cj03r_3YR1cyR9ilYYmYxUC14TkRtgLjH-Rc,5927
+py_cq/main.py,sha256=VKoXI8R8rB2fEROBYoTVURfinLqyh8XTNIIWAOtH7dw,380
+py_cq/metric_aggregator.py,sha256=M2ymo62S7p7qPUqjjoiPg4IVyXQhLMuTr9-jxLiFjCY,853
+py_cq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py_cq/tool_registry.py,sha256=Ov5kQIRc5C5vkAq5Nc2Otp5kYiQzJuK5_nA-ZkY_-NQ,1529
+py_cq/config/__init__.py,sha256=f0wc51O_3kGDTZUnCbGv8_zWnC5yYGl4NWcf2buSImQ,670
+py_cq/config/tools.yaml,sha256=cNs4h4sIJA-j28QhEFG0uWL9ELaPy_z8BNo4l5F3is4,2553
+py_cq/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py_cq/parsers/banditparser.py,sha256=vj23tTbipaeVkhS_ldWI7GrpHGwlIkOuaEgszkrjzh0,2277
+py_cq/parsers/common.py,sha256=lc9Chtr3H5l3vTk-vRVhptQVJfOeLax0UWTRjhA9IOU,4044
+py_cq/parsers/compileparser.py,sha256=mVY8qh1oZQ8n9GJLW2ruF9j89G5GuxWb7fb6JeogTJ4,6207
+py_cq/parsers/complexityparser.py,sha256=2t1-wmNjUu65fULcIm5jcgv7ZLWwjakyiY_r-Fx1QQg,3983
+py_cq/parsers/coverageparser.py,sha256=xDNlLNEsA0U3z4GV02iEq97IL90-UJAQrhMlFzpIdy0,4013
+py_cq/parsers/halsteadparser.py,sha256=9z_abpPPuclUQBgq4P6u2vIfIB7ZShX2NbFnubTatqI,8980
+py_cq/parsers/interrogateparser.py,sha256=eMROINtyZE2eHrRxVU0jA-nYTdvr0PZ8iERVn7kPH5o,2197
+py_cq/parsers/maintainabilityparser.py,sha256=Ax0ZFA6zzqYIWZH1hP1_GUtdVn2LIJ8SKWtqVNdszYs,3411
+py_cq/parsers/pytestparser.py,sha256=ERgS1aTTi7aB-Xk_Y9Xpo9h5jT9n0q3_vAfHCZwBTFE,4539
+py_cq/parsers/ruffparser.py,sha256=Wgch9rDkR-6tJlfhDfG1CXXEZu0Gfk0qRpsI3KzjCZU,2226
+py_cq/parsers/typarser.py,sha256=u7ktoH0TzmhB2saCJF1iY1LkfGui5ami2leLlYSCcns,2446
+py_cq/parsers/vultureparser.py,sha256=X2fen6yQu-r_zoRt1qKfIGlGZKORkHCiZE4BFlxtzdE,1946
+python_code_quality-0.1.8.dist-info/METADATA,sha256=2-E2SuWhsQMwYtv4NERKmE9CajsglC81tZY5DPPefrc,10266
+python_code_quality-0.1.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_code_quality-0.1.8.dist-info/entry_points.txt,sha256=j5Q_gGr0b7389lddt1JlZ7gcL4Z7RHxuDhij_G-IhBY,39
+python_code_quality-0.1.8.dist-info/licenses/LICENSE,sha256=Bpuh8tbf37so8M5NtRGTLmT5ue7diJ17223L9f9nsT0,1086
+python_code_quality-0.1.8.dist-info/RECORD,,

py_cq/storage.py

@@ -1,27 +0,0 @@
-"""Utilities for persisting combined tool results.
-
-This module provides a single helper function, :func:`save_result`, which
-serializes a :class:`CombinedToolResults` instance to a JSON file. The
-function ensures that the target directory exists, writes a readable
-representation of the results, and returns the absolute path of the created
-file.
-
-Example
--------
->>> from your_package import CombinedToolResults, save_result
->>> results = CombinedToolResults(...)
->>> output_path = save_result(results, "output.json")
->>> print(output_path)"""
-
-import json
-
-from py_cq.localtypes import CombinedToolResults
-
-
-def save_result(combined_tool_results: CombinedToolResults, file_name: str):
-    """Saves combined tool results to a JSON file named by `file_name`."""
-    if not file_name:
-        return
-    data = combined_tool_results.to_dict()
-    with open(file_name, "w") as f:
-        json.dump(data, f, indent=4)

python_code_quality-0.1.6.dist-info/RECORD

@@ -1,31 +0,0 @@
-py_cq/__init__.py,sha256=rS7kf1RU1zZskvJlkbZaMqEpdRYPspwDPAFbxzF3tXg,373
-py_cq/cli.py,sha256=M0t5noGEt-a1TmTaDvsGKfApcpOZnXjXHiUo_tSdcjk,8586
-py_cq/context_hash.py,sha256=h-i7Rhd7AUfLv9SkQvE79bjJvTsm_ZwoVwSmUKXWmfM,2977
-py_cq/execution_engine.py,sha256=xNZHLVbkNf97FwDI29R1_njyy-xrlHD_RDUX86PLlQU,6675
-py_cq/llm_formatter.py,sha256=tOjoWIFEq3ZRGKLcwAnLswQ00B79sM3yJT3K3bh857A,1577
-py_cq/localtypes.py,sha256=Ix871IDcZh8_EldhOrmvR4TPxvWfDi0YhZVSGpI6pl0,5961
-py_cq/main.py,sha256=VKoXI8R8rB2fEROBYoTVURfinLqyh8XTNIIWAOtH7dw,380
-py_cq/metric_aggregator.py,sha256=M2ymo62S7p7qPUqjjoiPg4IVyXQhLMuTr9-jxLiFjCY,853
-py_cq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-py_cq/storage.py,sha256=J8360OUnGFyQAl_jJ6Eoy5hn7DDpShQvqaU6dFtfrkc,916
-py_cq/tool_registry.py,sha256=9QFqeXxrK7NF-qMd9ZxP5zfqc0nsHVQAbrbAqinAA4g,1535
-py_cq/config/__init__.py,sha256=JZgIe38Lq0XYd-zwOVzi6SxobYBc4lofhidmU4T9_oU,730
-py_cq/config/tools.yaml,sha256=ajZANuj2vBsXF70dVzFW1zMvNjnJ9ns3kkIr2P6Cexg,2518
-py_cq/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-py_cq/parsers/banditparser.py,sha256=G4wg7Jry6GsrHm5LOfTAvBuwoA6PvGqz8OKdNf0Ifs4,2219
-py_cq/parsers/common.py,sha256=FWkQIm03IKoCB7pvW4MRbQKjC_quINIKkGq5xKk86qM,3506
-py_cq/parsers/compileparser.py,sha256=GcIcKGVSL8W3zTwfA7WzD045-gNdSeSkljOrPA0qG0M,6496
-py_cq/parsers/complexityparser.py,sha256=2t1-wmNjUu65fULcIm5jcgv7ZLWwjakyiY_r-Fx1QQg,3983
-py_cq/parsers/coverageparser.py,sha256=xDNlLNEsA0U3z4GV02iEq97IL90-UJAQrhMlFzpIdy0,4013
-py_cq/parsers/halsteadparser.py,sha256=Rj690m_C4KRdlfrTC_bXtT5_-oJPKT38I7V-v1CDoJY,8980
-py_cq/parsers/interrogateparser.py,sha256=eMROINtyZE2eHrRxVU0jA-nYTdvr0PZ8iERVn7kPH5o,2197
-py_cq/parsers/maintainabilityparser.py,sha256=Ax0ZFA6zzqYIWZH1hP1_GUtdVn2LIJ8SKWtqVNdszYs,3411
-py_cq/parsers/pytestparser.py,sha256=FrAaNJfDHZmEr_vRYQpp04qRj4Cq3jaDhpnAFxLv5dQ,4047
-py_cq/parsers/ruffparser.py,sha256=WMJhsYA5wwBcIhqGSfjBxy78RGv_iCJJ1Qdmt1dqTOw,2567
-py_cq/parsers/typarser.py,sha256=bC6-P-NGBMJBLyr1DkX1yMtnTS8afuRO0Keb_XyBeg0,2787
-py_cq/parsers/vultureparser.py,sha256=fe-LPagivKGtmf6Kyu_gT0OrWJjowAsJ2OhXQiv_zQY,1888
-python_code_quality-0.1.6.dist-info/METADATA,sha256=90Ylk0f3eOWGyq2Nw1OmoZ0897OEzTQay0lSfLY-EtY,6745
-python_code_quality-0.1.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-python_code_quality-0.1.6.dist-info/entry_points.txt,sha256=j5Q_gGr0b7389lddt1JlZ7gcL4Z7RHxuDhij_G-IhBY,39
-python_code_quality-0.1.6.dist-info/licenses/LICENSE,sha256=Bpuh8tbf37so8M5NtRGTLmT5ue7diJ17223L9f9nsT0,1086
-python_code_quality-0.1.6.dist-info/RECORD,,