python-code-quality 0.1.6__tar.gz → 0.1.8__tar.gz

{python_code_quality-0.1.6 → python_code_quality-0.1.8}/CLAUDE.md

@@ -11,7 +11,7 @@ cq check -o llm   # returns the single most critical defect as markdown
 ```
 
 The LLM fixes it, the user re-runs, and repeats until all tools pass. CQ runs
-11 static analysis tools in priority order (compile → security → lint → types →
+11 static analysis tools in execution order (compile → security → lint → types →
 tests → coverage → complexity → dead code → style) and aggregates results into
 a single score.
 
@@ -40,15 +40,15 @@ uv run ruff check src/
 
 - **`cli.py`**: Typer app with a single `check` command. Output mode selected via `--output`/`-o` enum (`table`, `score`, `json`, `llm`). Runs tools in parallel by default. Reads `[tool.cq]` from the target project's `pyproject.toml` and applies overrides before running.
 - **`tool_registry.py`**: Loads `src/cq/config/tools.yaml` at import time via `importlib.resources`, dynamically imports parser classes, builds a `dict[str, ToolConfig]` registry.
-- **`config/tools.yaml`** (at `src/cq/config/tools.yaml`): Declares each analysis tool: shell command template (with `{context_path}` placeholder), parser class name, priority, warning/error thresholds. Tools are listed and executed in priority order.
-- **`execution_engine.py`**: Runs shell commands via `subprocess.run`, caches results with `diskcache` using a content-based hash. Parallel execution via `ThreadPoolExecutor`; results are sorted by priority before returning.
+- **`config/tools.yaml`** (at `src/cq/config/tools.yaml`): Declares each analysis tool: shell command template (with `{context_path}` placeholder), parser class name, order, warning/error thresholds. Tools are listed and executed in order.
+- **`execution_engine.py`**: Runs shell commands via `subprocess.run`, caches results with `diskcache` using a content-based hash. Parallel execution via `ThreadPoolExecutor`; results are sorted by order before returning.
 - **`parsers/`**: Each parser subclasses `AbstractParser` (from `localtypes.py`), implementing `parse(RawResult) -> ToolResult` and optionally `format_llm_message(ToolResult) -> str`. Parser module names must match the lowercase parser class name (e.g., `PytestParser` → `pytestparser.py`).
 - **`localtypes.py`**: Core dataclasses — `ToolConfig`, `RawResult`, `ToolResult`, `CombinedToolResults`, and `AbstractParser` ABC.
 - **`metric_aggregator.py`**: Wraps results into `CombinedToolResults`, which computes an overall score as the average of per-tool mean metrics.
-- **`llm_formatter.py`**: Selects the worst-scoring tool by severity tier then priority, formats its top defect as markdown for LLM consumption.
+- **`llm_formatter.py`**: Selects the worst-scoring tool by severity tier then order, formats its top defect as markdown for LLM consumption.
 
 ## Adding a New Analysis Tool
 
-1. Add tool entry in `config/tools.yaml` with command template, parser name, priority, and thresholds.
+1. Add tool entry in `config/tools.yaml` with command template, parser name, order, and thresholds.
 2. Create `src/cq/parsers/<parsername>.py` with a class matching the `parser` field in YAML.
 3. The parser must subclass `AbstractParser` and implement `parse(RawResult) -> ToolResult`.

{python_code_quality-0.1.6 → python_code_quality-0.1.8}/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,296 @@
+# CQ - Python Code Quality Analysis Tool
+
+Feed the results from 11+ code quality tools to an LLM. Minimal tokens.
+
+The primary workflow is:
+
+```bash
+# 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
+
+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, clone it then install 
+git pull https://github.com/rhiza-fr/py-cq.git
+cd py-cq
+uv tool install .
+```
+
+## Tools
+
+These tools are run in **parallel** except when looking for the first error in -o llm mode:
+
+| Order | Tool | Measures |
+|----------|------|----------|
+| 1 | compileall | Syntax errors |
+| 2 | bandit | Security vulnerabilities |
+| 3 | ruff | Lint / style |
+| 4 | ty | Type errors |
+| 5 | pytest | Test pass rate |
+| 6 | coverage | Test coverage |
+| 7 | radon cc | Cyclomatic complexity |
+| 8 | radon mi | Maintainability index |
+| 9 | radon hal | Halstead volume / bug estimate |
+| 10 | vulture | Dead code |
+| 11 | interrogate | Docstring coverage |
+
+Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, No pickle
+
+
+## Usage
+
+```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
+```
+
+## Table output
+
+```bash
+> cq check .
+```
+
+```python
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
+┃ Tool             ┃     Time ┃                    Metric ┃ Score   ┃ Status   ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
+│ compile          │    0.42s │                   compile │ 1.000   │ OK       │
+│ bandit           │    0.56s │                  security │ 1.000   │ OK       │
+│ ruff             │    0.17s │                      lint │ 1.000   │ OK       │
+│ ty               │    0.33s │                type_check │ 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       │
+│                  │          │                     Score │ 0.965   │          │
+└──────────────────┴──────────┴───────────────────────────┴─────────┴──────────┘
+```
+
+## Single score output
+```bash
+> cq check . -o score
+```
+```python
+0.9662730667181059 # this is designed to approach but not reach 1.0
+```
+
+## Json output
+```bash
+> cq check . -o json
+```
+
+```json
+[
+  {
+    "tool_name": "compile",
+    "metrics": {
+      "compile": 1.0
+    },
+    "details": {},
+    "duration_s": 0.05611889995634556
+  }
+  ...
+]
+```
+
+## Raw output
+```bash
+> cq check -o raw
+```
+
+```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
+
+Add a `[tool.cq]` section to your project's `pyproject.toml`:
+
+```toml
+[tool.cq]
+# Skip tools that are slow or not relevant to your project
+disable = ["coverage", "interrogate"]
+
+# Override warning/error thresholds per tool
+[tool.cq.thresholds.coverage]
+warning = 0.9
+error = 0.7
+```
+
+Tool IDs match the keys in `config/tools.yaml`: `compilation`, `bandit`, `ruff`, `ty`, `pytest`, `coverage`, `complexity`, `maintainability`, `halstead`, `vulture`, `interrogate`.
+
+
+### 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
+
+```
+
+## Respect
+
+Many thanks to all the wonderful maintainers of :
+
+- [compileall](https://docs.python.org/3/library/compileall.html)
+- [bandit](https://github.com/PyCQA/bandit)
+- [ruff](https://github.com/astral-sh/ruff)
+- [ty](https://github.com/astral-sh/ty)
+- [pytest](https://github.com/pytest-dev/pytest)
+- [coverage.py](https://github.com/nedbat/coveragepy)
+- [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.6 → python_code_quality-0.1.8}/pyproject.toml

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