python-code-quality 0.1.15__tar.gz → 0.2.1__tar.gz

{python_code_quality-0.1.15 → python_code_quality-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-code-quality
-Version: 0.1.15
+Version: 0.2.1
 Summary: Python Code Quality Analysis Tool - feed the results from 11 CQ tools straight into an LLM. Minimal tokens.
 Author: Chris Kilner
 Author-email: Chris Kilner <chris@rhiza.fr>
@@ -15,10 +15,10 @@ 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: pyyaml>=6.0.2
 Requires-Dist: radon>=6.0.1
 Requires-Dist: rich>=14.0.0
 Requires-Dist: ruff>=0.14.1
+Requires-Dist: tomlkit>=0.13.0
 Requires-Dist: ty>=0.0.17
 Requires-Dist: typer>=0.16.0
 Requires-Dist: vulture>=2.14
@@ -88,6 +88,7 @@ Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults
 ```bash
 cq check .                 # Table overview of scores for humans
 cq check . -o llm          # Top defect as markdown for LLMs
+cq check . -o llm-json     # Top defect as JSON with fingerprint (for automation)
 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
@@ -97,7 +98,9 @@ cq check . --skip bandit   # Skip specific tools
 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 is-fixed <fingerprint>  # Check whether a specific issue has been resolved
 ```
 
 **Exit codes:** `cq check` exits with code `1` if any tool metric falls below its `error_threshold`, making it suitable as a CI gate:
@@ -107,6 +110,88 @@ cq check . && deploy        # block deploy on errors
 cq check . -o score         # print score, exit 1 on errors
 ```
 
+## Fingerprint-based verification
+
+`-o llm-json` returns a JSON object with a stable `id` fingerprint you can pass back to `cq is-fixed` to check whether a specific issue has been resolved — without re-running all tools:
+
+```bash
+# Get the top defect as JSON
+cq check . -o llm-json
+```
+
+```json
+{
+  "id": "ruff::my-project::src/foo.py::42::E501",
+  "file": "src/foo.py",
+  "project": "/home/user/my-project",
+  "message": "..."
+}
+```
+
+```bash
+# After fixing, verify only that issue (fast — reruns one tool on one file)
+cq is-fixed "ruff::my-project::src/foo.py::42::E501"
+```
+
+This is most useful in automation: fix an issue, confirm it's gone, then fetch the next one. Note that this only verifies the original issue is no longer present — a full project-wide scan is still needed to guarantee no regressions, assuming you have sufficient tests.
+
+## Python Library
+
+`py_cq` can be used as a library — no subprocess required. Instantiate `CQ` with a project root; config is loaded once from `pyproject.toml`.
+
+```python
+from py_cq import CQ
+
+cq = CQ(".")                      # load config from ./pyproject.toml
+cq = CQ(".", skip=["bandit"])     # skip specific tools
+cq = CQ(".", only=["ruff", "ty"]) # run only specific tools
+cq = CQ(".", workers=4)           # control parallelism
+```
+
+**Methods mirror the CLI and return data objects:**
+
+```python
+# list[ToolResult] — all parsed results before aggregation (-o raw / -o json)
+results = cq.raw()
+
+# CombinedToolResults — aggregated score and per-tool results (-o score / table)
+combined = cq.check()
+print(combined.score)          # float
+print(combined.tool_results)   # list[ToolResult]
+
+# dict — top defect as JSON, equivalent to -o llm-json
+issue = cq.check_llm_json()
+issue["id"]       # fingerprint: "ruff::project::src/foo.py::42::E501"
+issue["file"]     # "src/foo.py"
+issue["message"]  # markdown prompt ready to send to an LLM
+issue["project"]  # absolute project root path
+
+# bool — True if the fingerprinted issue is gone
+# Reruns only the affected tool on the affected file — much faster than a full check.
+# Pass the id from check_llm_json; also available as `cq is-fixed <id>` on the CLI.
+fixed = cq.is_fixed(issue["id"])
+```
+
+`check_llm_json` accepts the same options as `cq check . -o llm-json`:
+
+```python
+issue = cq.check_llm_json(limit=3, silence=["src/generated.py"], hint=True)
+```
+
+**Typical automation loop:**
+
+```python
+from py_cq import CQ
+
+cq = CQ(".")
+while True:
+    issue = cq.check_llm_json()
+    if issue["id"] is None:
+        break                        # all clear
+    fix(issue["message"])            # call your LLM
+    assert cq.is_fixed(issue["id"])
+```
+
 ## 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:
@@ -346,7 +431,7 @@ python:
     error_threshold: 0.8
 
   interrogate:
-    command: "{python} -m interrogate \"{context_path}\" -e tests{exclude} -v --fail-under 0"
+    command: "{python} -m interrogate \"{context_path}\"{exclude} -v --fail-under 0"
     exclude_format: " -e {path}"
     parser: "InterrogateParser"
     order: 11

{python_code_quality-0.1.15 → python_code_quality-0.2.1}/README.md

@@ -59,6 +59,7 @@ Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults
 ```bash
 cq check .                 # Table overview of scores for humans
 cq check . -o llm          # Top defect as markdown for LLMs
+cq check . -o llm-json     # Top defect as JSON with fingerprint (for automation)
 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
@@ -68,7 +69,9 @@ cq check . --skip bandit   # Skip specific tools
 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 is-fixed <fingerprint>  # Check whether a specific issue has been resolved
 ```
 
 **Exit codes:** `cq check` exits with code `1` if any tool metric falls below its `error_threshold`, making it suitable as a CI gate:
@@ -78,6 +81,88 @@ cq check . && deploy        # block deploy on errors
 cq check . -o score         # print score, exit 1 on errors
 ```
 
+## Fingerprint-based verification
+
+`-o llm-json` returns a JSON object with a stable `id` fingerprint you can pass back to `cq is-fixed` to check whether a specific issue has been resolved — without re-running all tools:
+
+```bash
+# Get the top defect as JSON
+cq check . -o llm-json
+```
+
+```json
+{
+  "id": "ruff::my-project::src/foo.py::42::E501",
+  "file": "src/foo.py",
+  "project": "/home/user/my-project",
+  "message": "..."
+}
+```
+
+```bash
+# After fixing, verify only that issue (fast — reruns one tool on one file)
+cq is-fixed "ruff::my-project::src/foo.py::42::E501"
+```
+
+This is most useful in automation: fix an issue, confirm it's gone, then fetch the next one. Note that this only verifies the original issue is no longer present — a full project-wide scan is still needed to guarantee no regressions, assuming you have sufficient tests.
+
+## Python Library
+
+`py_cq` can be used as a library — no subprocess required. Instantiate `CQ` with a project root; config is loaded once from `pyproject.toml`.
+
+```python
+from py_cq import CQ
+
+cq = CQ(".")                      # load config from ./pyproject.toml
+cq = CQ(".", skip=["bandit"])     # skip specific tools
+cq = CQ(".", only=["ruff", "ty"]) # run only specific tools
+cq = CQ(".", workers=4)           # control parallelism
+```
+
+**Methods mirror the CLI and return data objects:**
+
+```python
+# list[ToolResult] — all parsed results before aggregation (-o raw / -o json)
+results = cq.raw()
+
+# CombinedToolResults — aggregated score and per-tool results (-o score / table)
+combined = cq.check()
+print(combined.score)          # float
+print(combined.tool_results)   # list[ToolResult]
+
+# dict — top defect as JSON, equivalent to -o llm-json
+issue = cq.check_llm_json()
+issue["id"]       # fingerprint: "ruff::project::src/foo.py::42::E501"
+issue["file"]     # "src/foo.py"
+issue["message"]  # markdown prompt ready to send to an LLM
+issue["project"]  # absolute project root path
+
+# bool — True if the fingerprinted issue is gone
+# Reruns only the affected tool on the affected file — much faster than a full check.
+# Pass the id from check_llm_json; also available as `cq is-fixed <id>` on the CLI.
+fixed = cq.is_fixed(issue["id"])
+```
+
+`check_llm_json` accepts the same options as `cq check . -o llm-json`:
+
+```python
+issue = cq.check_llm_json(limit=3, silence=["src/generated.py"], hint=True)
+```
+
+**Typical automation loop:**
+
+```python
+from py_cq import CQ
+
+cq = CQ(".")
+while True:
+    issue = cq.check_llm_json()
+    if issue["id"] is None:
+        break                        # all clear
+    fix(issue["message"])            # call your LLM
+    assert cq.is_fixed(issue["id"])
+```
+
 ## 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:
@@ -317,7 +402,7 @@ python:
     error_threshold: 0.8
 
   interrogate:
-    command: "{python} -m interrogate \"{context_path}\" -e tests{exclude} -v --fail-under 0"
+    command: "{python} -m interrogate \"{context_path}\"{exclude} -v --fail-under 0"
     exclude_format: " -e {path}"
     parser: "InterrogateParser"
     order: 11

{python_code_quality-0.1.15 → python_code_quality-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-code-quality"
-version = "0.1.15"
+version = "0.2.1"
 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"
@@ -20,10 +20,10 @@ dependencies = [
     "pytest>=8.4.0",
     "pytest-cov>=6.1.1",
     "pytest-json-report>=1.5.0",
-    "pyyaml>=6.0.2",
     "radon>=6.0.1",
     "rich>=14.0.0",
     "ruff>=0.14.1",
+    "tomlkit>=0.13.0",
     "ty>=0.0.17",
     "typer>=0.16.0",
     "vulture>=2.14",
@@ -46,6 +46,19 @@ cq = "py_cq.main:main"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 norecursedirs = [".venv", "dist"]
+markers = [
+    "slow: tests that have real side effects (e.g. clearing disk cache)",
+]
+addopts = "-m 'not slow'"
+
+[[tool.ty.overrides]]
+include = ["demo/**"]
+rules = {unresolved-import = "ignore"}
 
 [tool.cq]
 exclude = ["demo"]
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.151.10",
+]

python_code_quality-0.2.1/src/py_cq/__init__.py

@@ -0,0 +1,5 @@
+"""Py cq"""
+
+from py_cq.api import CQ
+
+__all__ = ["CQ"]

python_code_quality-0.2.1/src/py_cq/api.py

@@ -0,0 +1,248 @@
+"""Library API for py-cq. Instantiate CQ with a project root, then call methods."""
+
+import copy
+from importlib import import_module
+from pathlib import Path
+
+from py_cq.config import load_user_config
+from py_cq.execution_engine import _cache, run_tools
+from py_cq.llm_formatter import format_for_llm_json
+from py_cq.localtypes import CombinedToolResults, Fingerprint, ToolConfig, ToolResult
+from py_cq.metric_aggregator import aggregate_metrics
+from py_cq.tool_registry import tool_registry
+
+_KNOWN_PARSER_CLASSES = frozenset(
+    {
+        "CompileParser",
+        "RuffParser",
+        "TyParser",
+        "BanditParser",
+        "PytestParser",
+        "CoverageParser",
+        "ComplexityParser",
+        "MaintainabilityParser",
+        "HalsteadParser",
+        "VultureParser",
+        "InterrogateParser",
+        "ExitCodeParser",
+        "LineCountParser",
+        "RegexCountParser",
+    }
+)
+
+
+def _apply_user_config(
+    base: dict[str, ToolConfig], user_cfg: dict
+) -> dict[str, ToolConfig]:
+    """Return a modified copy of base with user overrides applied.
+
+    Raises ValueError on invalid config (caller wraps for CLI context).
+    """
+    registry = {k: copy.copy(v) for k, v in base.items()}
+    for tool_id in user_cfg.get("disable", []):
+        registry.pop(tool_id, None)
+    for tool_id, thresholds in user_cfg.get("thresholds", {}).items():
+        if tool_id in registry:
+            if "warning" in thresholds:
+                registry[tool_id].warning_threshold = float(thresholds["warning"])
+            if "error" in thresholds:
+                registry[tool_id].error_threshold = float(thresholds["error"])
+    for tool_id, tool_data in user_cfg.get("tools", {}).items():
+        if tool_id in base:
+            available = ", ".join(sorted(base))
+            raise ValueError(
+                f"[tool.cq.tools.{tool_id}] is a built-in tool and cannot be redefined via pyproject.toml. "
+                f"Use [tool.cq.thresholds.{tool_id}] to adjust thresholds instead. "
+                f"Available: {available}"
+            )
+        try:
+            parser_name = tool_data["parser"]
+        except KeyError:
+            raise ValueError(
+                f"[tool.cq.tools.{tool_id}] missing required field 'parser'"
+            )
+        if parser_name not in _KNOWN_PARSER_CLASSES:
+            allowed = ", ".join(sorted(_KNOWN_PARSER_CLASSES))
+            raise ValueError(
+                f"[tool.cq.tools.{tool_id}] unknown parser {parser_name!r}. "
+                f"Allowed parsers: {allowed}"
+            )
+        try:
+            module = import_module(f"py_cq.parsers.{parser_name.lower()}")
+            parser_class = getattr(module, parser_name)
+            registry[tool_id] = ToolConfig(
+                name=tool_id,
+                command=tool_data["command"],
+                parser_class=parser_class,
+                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),
+                extra_deps=tool_data.get("extra_deps", []),
+                parser_config=tool_data.get("parser_config", {}),
+                exclude_format=tool_data.get("exclude_format", ""),
+            )
+        except (KeyError, ImportError, AttributeError) as e:
+            raise ValueError(f"[tool.cq.tools.{tool_id}] {e}")
+    return registry
+
+
+class CQ:
+    """Run code quality checks against a project root.
+
+    Config is loaded once at construction from pyproject.toml [tool.cq].
+    All methods return data objects; formatting is left to the caller.
+
+    Example::
+
+        cq = CQ(".")
+        issue = cq.check_llm_json()   # {"id": ..., "message": ..., "file": ..., "project": ...}
+        fixed = cq.is_fixed(issue["id"])
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        skip: list[str] | None = None,
+        only: list[str] | None = None,
+        exclude: list[str] | None = None,
+        workers: int = 0,
+        clear_cache: bool = False,
+    ) -> None:
+        self.path = Path(path)
+        self._workers = workers
+
+        user_cfg = load_user_config(self.path)
+        self._context_lines: int = int(user_cfg.get("context_lines", 15))
+        self._registry = _apply_user_config(tool_registry, user_cfg)
+
+        if self.path.is_file():
+            self._registry = {
+                k: v for k, v in self._registry.items() if not v.skip_for_file
+            }
+
+        if only:
+            keep = set(only)
+            unknown = keep - set(self._registry)
+            if unknown:
+                raise ValueError(
+                    f"Unknown tool(s): {', '.join(sorted(unknown))}. Available: {', '.join(sorted(self._registry))}"
+                )
+            self._registry = {k: v for k, v in self._registry.items() if k in keep}
+        if skip:
+            drop = set(skip)
+            unknown = drop - set(self._registry)
+            if unknown:
+                raise ValueError(
+                    f"Unknown tool(s): {', '.join(sorted(unknown))}. Available: {', '.join(sorted(self._registry))}"
+                )
+            self._registry = {k: v for k, v in self._registry.items() if k not in drop}
+
+        config_excludes: list[str] = user_cfg.get("exclude", [])
+        self._excludes = list(dict.fromkeys(config_excludes + (exclude or [])))
+        self._project_root = (
+            self.path.resolve() if self.path.is_dir() else self.path.resolve().parent
+        )
+
+        if clear_cache:
+            _cache.clear()
+
+    def raw(self, *, early_exit: bool = False) -> list[ToolResult]:
+        """Run all tools and return parsed results before aggregation."""
+        return run_tools(
+            self._registry.values(),
+            str(self.path),
+            self._workers,
+            early_exit=early_exit,
+            excludes=self._excludes,
+        )
+
+    def check(self) -> CombinedToolResults:
+        """Run all tools and return aggregated results."""
+        return aggregate_metrics(str(self.path), self.raw())
+
+    def check_llm_json(
+        self,
+        *,
+        limit: int = 1,
+        silence: list[str] | None = None,
+        hint: bool = False,
+    ) -> dict:
+        """Return the top defect as a dict with keys: id, file, project, message.
+
+        Stops running tools after the first error (early_exit) for speed.
+        """
+        results = self.raw(early_exit=True)
+        combined = aggregate_metrics(str(self.path), results)
+        return format_for_llm_json(
+            self._registry,
+            combined,
+            context_lines=self._context_lines,
+            hint=hint,
+            limit=limit,
+            silence=silence or [],
+            project_root=self._project_root,
+        )
+
+    def is_fixed(self, fingerprint: str) -> bool:
+        """Return True if the fingerprinted issue is no longer present.
+
+        Fingerprint format: ``tool::project::path[::line[::code]]``  (as returned by check_llm_json["id"])
+        """
+        fp = Fingerprint.from_string(fingerprint)
+        if not fp.tool:
+            raise ValueError(
+                f"Expected tool::project::path[::line[::code]], got: {fingerprint!r}"
+            )
+        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)
+            if not file_path.is_absolute():
+                base = Path(fp.project) if fp.project else self._project_root
+                file_path = (base / file_path) if base else file_path
+            target = str(file_path)
+        elif fp.project and Path(fp.project).is_dir():
+            target = fp.project
+        elif fp.path:
+            file_path = Path(fp.path)
+            if not file_path.is_absolute():
+                file_path = (
+                    (self._project_root / file_path)
+                    if self._project_root
+                    else file_path
+                )
+            target = str(file_path)
+        else:
+            target = str(self.path)
+
+        only_registry = {fp.tool: tool_registry[fp.tool]}
+        tool_results = run_tools(
+            only_registry.values(), target, max_workers=1, early_exit=False, excludes=[],
+            project_root=str(self.path),
+        )
+
+        if not tool_results:
+            return False
+
+        tr = tool_results[0]
+        tc = tool_registry[fp.tool]
+
+        if not fp.code:
+            return bool(tr.metrics and min(tr.metrics.values()) >= tc.warning_threshold)
+
+        def _file_matches(detail_file: str) -> bool:
+            p = Path(detail_file).as_posix()
+            t = Path(fp.path).as_posix()
+            return p == t or p.endswith(f"/{t}") or t.endswith(f"/{p}")
+
+        still_present = any(
+            str(i.get("line", "")) == fp.line and i.get("code") == fp.code
+            for f, issues in tr.details.items()
+            if _file_matches(f) and isinstance(issues, list)
+            for i in issues
+        )
+        return not still_present