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

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

@@ -1,20 +1,17 @@
 Metadata-Version: 2.4
 Name: python-code-quality
-Version: 0.1.8
+Version: 0.1.10
 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: Chris Kilner
 Author-email: Chris Kilner <chris@rhiza.fr>
 License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.12
 Requires-Dist: bandit>=1.8.0
 Requires-Dist: coverage>=7.8.2
 Requires-Dist: diskcache>=5.6.3
 Requires-Dist: interrogate>=1.7.0
+Requires-Dist: pytest>=8.4.0
 Requires-Dist: pytest-cov>=6.1.1
 Requires-Dist: pytest-json-report>=1.5.0
-Requires-Dist: pytest>=8.4.0
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: radon>=6.0.1
 Requires-Dist: rich>=14.0.0
@@ -22,26 +19,25 @@ Requires-Dist: ruff>=0.14.1
 Requires-Dist: ty>=0.0.17
 Requires-Dist: typer>=0.16.0
 Requires-Dist: vulture>=2.14
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/rhiza-fr/py-cq
+Project-URL: Repository, https://github.com/rhiza-fr/py-cq
 Description-Content-Type: text/markdown
 
 # CQ - Python Code Quality Analysis Tool
 
 Feed the results from 11+ code quality tools to an LLM. Minimal tokens.
 
+Why? It removes the mental burden of understanding all these tools and parsing their results.
+
 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
+```python
 `data/problems/travelling_salesman/ts_bad.py:21` — **F841**: Local variable `unused_variable` is assigned to but never used
 
 18:     min_dist = float("inf")
@@ -60,9 +56,10 @@ 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"
+cq check . -o llm | ollama run gpt-oss:20b "Explain how to fix this"
 ```
 
+
 ## Install
 
 ```bash
@@ -70,21 +67,22 @@ cq check . -o llm | ollama gpt-oss:20b "Explain how to fix this"
 uv tool install python-code-quality
 
 # or, clone it then install 
-git pull https://github.com/rhiza-fr/py-cq.git
+git clone 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:
+These tools are run in **parallel** except:
+When running '-o llm', we run sequentially and exit early at the first error.
 
 | Order | Tool | Measures |
 |----------|------|----------|
 | 1 | compileall | Syntax errors |
-| 2 | bandit | Security vulnerabilities |
-| 3 | ruff | Lint / style |
-| 4 | ty | Type errors |
+| 2 | ruff | Lint / style |
+| 3 | ty | Type errors |
+| 4 | bandit | Security vulnerabilities |
 | 5 | pytest | Test pass rate |
 | 6 | coverage | Test coverage |
 | 7 | radon cc | Cyclomatic complexity |
@@ -93,14 +91,14 @@ These tools are run in **parallel** except when looking for the first error in -
 | 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
+Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, No pickle risk.
 
 
 ## Usage
 
 ```bash
 cq check .                 # Table overview of scores for humans
-cq check -o llm            # Top defect as markdown for LLMs
+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
@@ -110,6 +108,46 @@ cq check . --clear-cache   # Clear cached results before running (rarely needed)
 cq config path/to/project/ # Show effective tool configuration
 ```
 
+**Exit codes:** `cq check` exits with code `1` if any tool metric falls below its `error_threshold`, making it suitable as a CI gate:
+
+```bash
+cq check . && deploy        # block deploy on errors
+cq check . -o score         # print score, exit 1 on errors
+```
+
+## Claude Code Integration
+
+Add a stop hook to your project's `.claude/settings.json` so Claude automatically checks quality after each session and loops until clean:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "",
+      "hooks": [{"type": "command", "command": "cq check . -o score && echo 'CQ: all clear' || cq check . -o llm"}]
+    }]
+  }
+}
+```
+
+When the score passes, Claude sees `CQ: all clear` (~5 tokens). When it fails, Claude receives the targeted fix prompt and continues working. This automates the `cq check . -o llm | claude -p "fix this"` loop.
+
+> **Note:** Use project-level `.claude/settings.json`, not global settings — this hook only makes sense in Python projects.
+
+### As a slash command (skill)
+
+For manual invocation, create `.claude/commands/cq-fix.md`:
+
+```markdown
+$(cq check . -o llm)
+```
+
+Then invoke it with `/cq-fix` in Claude Code. The `$(...)` embeds the live `cq` output directly into the prompt before Claude starts, so it sees the issue immediately without an extra tool call.
+
+**Hook vs skill:**
+- **Stop hook** — automatic, runs after every session, best for unattended loops
+- **Skill** — manual `/cq-fix`, gives you explicit control over when to check
+
 ## Table output
 
 ```bash
@@ -121,9 +159,9 @@ cq config path/to/project/ # Show effective tool configuration
 ┃ 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       │
+│ 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       │
@@ -167,7 +205,7 @@ cq config path/to/project/ # Show effective tool configuration
 
 ## Raw output
 ```bash
-> cq check -o raw
+> cq check . -o raw
 ```
 
 ```json
@@ -193,66 +231,63 @@ Add a `[tool.cq]` section to your project's `pyproject.toml`:
 # Skip tools that are slow or not relevant to your project
 disable = ["coverage", "interrogate"]
 
+# Lines of source context shown around each defect in LLM output (default: 15)
+context_lines = 15
+
 # 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`.
+Tool IDs match the keys in `config/config.yaml`: `compile`, `ruff`, `ty`, `bandit`, `pytest`, `coverage`, `radon-cc`, `radon-mi`, `radon-hal`, `vulture`, `interrogate`.
 
 
 ### Default config
 
 ```yaml
-tools:
+python:
 
-  compilation:
-    name: "compile"
+  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
+    order: 2
     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
+    order: 3
     warning_threshold: 0.9999
     error_threshold: 0.8
     run_in_target_env: true
     extra_deps:
       - ty
 
+  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: 4
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+
   pytest:
-    name: "pytest"
     command: "{python} -m pytest -v {context_path}"
     parser: "PytestParser"
     order: 5
-    warning_threshold: 0.7
-    error_threshold: 0.5
+    warning_threshold: 1.0
+    error_threshold: 1.0
     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
@@ -263,24 +298,21 @@ tools:
       - coverage
       - pytest
 
-  complexity:
-    name: "radon cc"
+  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"
+  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"
+  radon-hal:
     command: "{python} -m radon hal -f --json {context_path}"
     parser: "HalsteadParser"
     order: 9
@@ -288,7 +320,6 @@ tools:
     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
@@ -296,7 +327,6 @@ tools:
     error_threshold: 0.8
 
   interrogate:
-    name: "interrogate"
     command: "{python} -m interrogate {context_path} -v --fail-under 0"
     parser: "InterrogateParser"
     order: 11

{python_code_quality-0.1.8 → python_code_quality-0.1.10}/README.md

@@ -2,20 +2,16 @@
 
 Feed the results from 11+ code quality tools to an LLM. Minimal tokens.
 
+Why? It removes the mental burden of understanding all these tools and parsing their results.
+
 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
+```python
 `data/problems/travelling_salesman/ts_bad.py:21` — **F841**: Local variable `unused_variable` is assigned to but never used
 
 18:     min_dist = float("inf")
@@ -34,9 +30,10 @@ 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"
+cq check . -o llm | ollama run gpt-oss:20b "Explain how to fix this"
 ```
 
+
 ## Install
 
 ```bash
@@ -44,21 +41,22 @@ cq check . -o llm | ollama gpt-oss:20b "Explain how to fix this"
 uv tool install python-code-quality
 
 # or, clone it then install 
-git pull https://github.com/rhiza-fr/py-cq.git
+git clone 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:
+These tools are run in **parallel** except:
+When running '-o llm', we run sequentially and exit early at the first error.
 
 | Order | Tool | Measures |
 |----------|------|----------|
 | 1 | compileall | Syntax errors |
-| 2 | bandit | Security vulnerabilities |
-| 3 | ruff | Lint / style |
-| 4 | ty | Type errors |
+| 2 | ruff | Lint / style |
+| 3 | ty | Type errors |
+| 4 | bandit | Security vulnerabilities |
 | 5 | pytest | Test pass rate |
 | 6 | coverage | Test coverage |
 | 7 | radon cc | Cyclomatic complexity |
@@ -67,14 +65,14 @@ These tools are run in **parallel** except when looking for the first error in -
 | 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
+Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, No pickle risk.
 
 
 ## Usage
 
 ```bash
 cq check .                 # Table overview of scores for humans
-cq check -o llm            # Top defect as markdown for LLMs
+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
@@ -84,6 +82,46 @@ cq check . --clear-cache   # Clear cached results before running (rarely needed)
 cq config path/to/project/ # Show effective tool configuration
 ```
 
+**Exit codes:** `cq check` exits with code `1` if any tool metric falls below its `error_threshold`, making it suitable as a CI gate:
+
+```bash
+cq check . && deploy        # block deploy on errors
+cq check . -o score         # print score, exit 1 on errors
+```
+
+## Claude Code Integration
+
+Add a stop hook to your project's `.claude/settings.json` so Claude automatically checks quality after each session and loops until clean:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "",
+      "hooks": [{"type": "command", "command": "cq check . -o score && echo 'CQ: all clear' || cq check . -o llm"}]
+    }]
+  }
+}
+```
+
+When the score passes, Claude sees `CQ: all clear` (~5 tokens). When it fails, Claude receives the targeted fix prompt and continues working. This automates the `cq check . -o llm | claude -p "fix this"` loop.
+
+> **Note:** Use project-level `.claude/settings.json`, not global settings — this hook only makes sense in Python projects.
+
+### As a slash command (skill)
+
+For manual invocation, create `.claude/commands/cq-fix.md`:
+
+```markdown
+$(cq check . -o llm)
+```
+
+Then invoke it with `/cq-fix` in Claude Code. The `$(...)` embeds the live `cq` output directly into the prompt before Claude starts, so it sees the issue immediately without an extra tool call.
+
+**Hook vs skill:**
+- **Stop hook** — automatic, runs after every session, best for unattended loops
+- **Skill** — manual `/cq-fix`, gives you explicit control over when to check
+
 ## Table output
 
 ```bash
@@ -95,9 +133,9 @@ cq config path/to/project/ # Show effective tool configuration
 ┃ 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       │
+│ 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       │
@@ -141,7 +179,7 @@ cq config path/to/project/ # Show effective tool configuration
 
 ## Raw output
 ```bash
-> cq check -o raw
+> cq check . -o raw
 ```
 
 ```json
@@ -167,66 +205,63 @@ Add a `[tool.cq]` section to your project's `pyproject.toml`:
 # Skip tools that are slow or not relevant to your project
 disable = ["coverage", "interrogate"]
 
+# Lines of source context shown around each defect in LLM output (default: 15)
+context_lines = 15
+
 # 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`.
+Tool IDs match the keys in `config/config.yaml`: `compile`, `ruff`, `ty`, `bandit`, `pytest`, `coverage`, `radon-cc`, `radon-mi`, `radon-hal`, `vulture`, `interrogate`.
 
 
 ### Default config
 
 ```yaml
-tools:
+python:
 
-  compilation:
-    name: "compile"
+  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
+    order: 2
     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
+    order: 3
     warning_threshold: 0.9999
     error_threshold: 0.8
     run_in_target_env: true
     extra_deps:
       - ty
 
+  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: 4
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+
   pytest:
-    name: "pytest"
     command: "{python} -m pytest -v {context_path}"
     parser: "PytestParser"
     order: 5
-    warning_threshold: 0.7
-    error_threshold: 0.5
+    warning_threshold: 1.0
+    error_threshold: 1.0
     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
@@ -237,24 +272,21 @@ tools:
       - coverage
       - pytest
 
-  complexity:
-    name: "radon cc"
+  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"
+  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"
+  radon-hal:
     command: "{python} -m radon hal -f --json {context_path}"
     parser: "HalsteadParser"
     order: 9
@@ -262,7 +294,6 @@ tools:
     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
@@ -270,7 +301,6 @@ tools:
     error_threshold: 0.8
 
   interrogate:
-    name: "interrogate"
     command: "{python} -m interrogate {context_path} -v --fail-under 0"
     parser: "InterrogateParser"
     order: 11

{python_code_quality-0.1.8 → python_code_quality-0.1.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-code-quality"
-version = "0.1.8"
+version = "0.1.10"
 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"
@@ -29,11 +29,11 @@ Homepage = "https://github.com/rhiza-fr/py-cq"
 Repository = "https://github.com/rhiza-fr/py-cq"
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["uv_build"]
+build-backend = "uv_build"
 
-[tool.hatch.build.targets.wheel]
-packages = ["src/py_cq"]
+[tool.uv.build-backend]
+module-name = "py_cq"
 
 [project.scripts]
 cq = "py_cq.main:main"