python-code-quality 0.2.3__py3-none-any.whl → 0.3.1__py3-none-any.whl

py_cq/api.py

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

py_cq/cli.py

@@ -17,7 +17,7 @@ import logging
 import time
 import tomllib
 from enum import Enum
-from importlib.metadata import requires, version
+from importlib.metadata import PackageNotFoundError, requires, version
 from pathlib import Path
 
 import tomlkit
@@ -88,7 +88,7 @@ def _version_callback(value: bool) -> None:
         dep_name = re.split(r"[>=<!;\s\[]", req)[0]
         try:
             dep_versions.append((dep_name, version(dep_name)))
-        except Exception:
+        except PackageNotFoundError:
             pass
     typer.echo(f"{pkg} v{pkg_version}")
     for dep_name, dep_ver in sorted(dep_versions):
@@ -107,7 +107,7 @@ def callback(
         help="Show version and dependencies",
     ),
 ) -> None:
-    """Feed the results from 11+ code quality tools to an LLM. Try: cq check . -o llm"""
+    """Feed the results from 12 code quality tools to an LLM. Try: cq check . -o llm"""
     import sys
 
     if isinstance(sys.stdout, io.TextIOWrapper):
@@ -120,11 +120,11 @@ console = Console()
 @app.command()
 def check(
     path: str = typer.Argument(".", help="Path to Python file or project directory"),
-    output: OutputMode = typer.Option(
+    output: OutputMode = typer.Option(  # noqa: B008
         OutputMode.TABLE,
         "--output",
         "-o",
-        help="Output mode: table (default), score, json, llm",
+        help="Output mode: table (default), score, json, raw, llm, llm-json",
     ),
     log_level: str = typer.Option(
         "CRITICAL",
@@ -160,19 +160,19 @@ def check(
     limit: int = typer.Option(
         1, "--limit", help="Number of issues to show with -o llm (default: 1)"
     ),
-    silence: list[str] = typer.Option(
+    silence: list[str] = typer.Option(  # noqa: B008
         [],
         "--silence",
         "-s",
         help="Silence issues from -o llm output (e.g. -s src/foo.py or -s src/foo.py:42:E501)",
     ),
-    order: OrderMode = typer.Option(
+    order: OrderMode = typer.Option(  # noqa: B008
         OrderMode.SEVERITY,
         "--order",
         help="Issue selection order for -o llm/llm-json: severity (most severe first) or phase (first non-clean phase, in dependency order)",
     ),
 ):
-    """Feed the results from 11+ code quality tools to an LLM. Try: cq check . -o llm"""  # --help
+    """Feed the results from 12 code quality tools to an LLM. Try: cq check . -o llm"""  # --help
     path_obj = Path(path)
     if not path_obj.exists():
         raise typer.BadParameter(f"Path does not exist: {path}")
@@ -186,12 +186,10 @@ def check(
         )
         raise typer.Exit(0)
 
-    if path_obj.is_file():
-        if path_obj.suffix != ".py":
-            raise typer.BadParameter(f"File must be a Python file (.py): {path}")
-    elif path_obj.is_dir():  # pragma: no branch
-        if not (path_obj / "pyproject.toml").exists():
-            raise typer.BadParameter(f"Directory must contain pyproject.toml: {path}")
+    if path_obj.is_file() and path_obj.suffix != ".py":
+        raise typer.BadParameter(f"File must be a Python file (.py): {path}")
+    elif path_obj.is_dir() and not (path_obj / "pyproject.toml").exists():
+        raise typer.BadParameter(f"Directory must contain pyproject.toml: {path}")
     log.setLevel(log_level)
 
     only_list = [t.strip() for t in only.split(",")] if only else None

py_cq/config/config.toml

@@ -4,6 +4,7 @@ parser = "CompileParser"
 order = 1
 warning_threshold = 0.9999
 error_threshold = 0.9999
+cache_invariant = "ast"
 
 [python.ruff]
 command = "{python} -m ruff check --output-format concise --no-cache \"{context_path}\" --exclude .claude{exclude}"
@@ -42,6 +43,7 @@ error_threshold = 1.0
 run_in_target_env = true
 extra_deps = ["pytest"]
 skip_for_file = true
+cache_invariant = "ast"
 
 [python.coverage]
 command = "{python} -m coverage run --omit=*/tests/*,*/test_*.py -m pytest \"{context_path}\" --ignore .claude{exclude} && {python} -m coverage report --show-missing --omit=*/tests/*,*/test_*.py"
@@ -54,6 +56,7 @@ run_in_target_env = true
 extra_deps = ["coverage", "pytest"]
 skip_for_file = true
 skip_if = "pytest"
+cache_invariant = "ast"
 
 [python.vulture]
 command = "{python} -m vulture \"{context_path}\" --min-confidence 80 --exclude .venv,dist,.*_cache,docs,.git,.claude{exclude}"
@@ -62,6 +65,7 @@ parser = "VultureParser"
 order = 7
 warning_threshold = 0.9999
 error_threshold = 0.8
+cache_invariant = "ast"
 
 [python.interrogate]
 command = "{python} -m interrogate \"{context_path}\" -e .claude{exclude} -v --fail-under 0"
@@ -97,3 +101,12 @@ order = 11
 gate_strict = false
 warning_threshold = 0.35
 error_threshold = 0.3
+
+[python.ruff-format]
+command = "{python} -m ruff format --check --output-format concise --no-cache \"{context_path}\" --exclude .claude --config \"include=['*.py','*.pyi','*.ipynb']\"{exclude}"
+exclude_format = " --exclude {path}"
+parser = "RuffFormatParser"
+order = 12
+gate_strict = false
+warning_threshold = 0.9999
+error_threshold = 0.5

py_cq/context_hash.py

@@ -12,23 +12,56 @@ change-detection in larger systems:
   a file or directory. For a file it hashes its path, size, and modification
   time; for a directory it aggregates the signatures of all contained files.
 
+When called with ``normalize=True`` the hash is derived from the AST of each
+``.py`` file with docstrings stripped, so changes that cannot affect runtime
+behaviour (docstrings, comments, formatting, mtime-only touches such as a
+``git checkout``) leave the hash unchanged. This is used as the cache key for
+tools whose results only depend on executable code (pytest, coverage).
+
 These functions provide deterministic fingerprints that can be used for
 file integrity verification, caching, and change-detection logic.
 """
 
 import hashlib
 import os
+from pathlib import Path
+
+from py_cq.source_file import get_source
+
+_ENV_FILES = {".python-version", "pyproject.toml", "uv.lock"}
+_SKIP_DIRS = {".venv", "venv", "__pycache__", ".git"}
 
 
-def get_sigs(path: str):
+def _normalized_sig(path: str) -> str:
+    """Return a docstring/comment/format-invariant signature for a ``.py`` file.
+
+    Backed by the shared :class:`~py_cq.source_file.SourceFile` cache, so the
+    AST parsed here is reused by the coverage and interrogate parsers. Falls
+    back to a byte digest when the file can't be parsed (e.g. a mid-edit syntax
+    error), so callers always get a usable signature.
+    """
+    return f"{path}:{get_source(path).norm_digest}"
+
+
+def _byte_sig(path: str) -> str:
+    """Return a path + content digest, independent of mtime."""
+    return f"{path}:{hashlib.md5(Path(path).read_bytes()).hexdigest()}"  # nosec
+
+
+def get_sigs(path: str, *, normalize: bool = False):
     """Recursively scans a directory tree and returns a list of signatures for all Python files.
 
     The signature format is ``<file_path>:<size_bytes>:<mtime>`` where ``mtime`` is the
     last modification timestamp retrieved from ``os.stat``. The traversal skips
     directories named ``.venv``, ``venv`` and ``__pycache__``.
 
+    When ``normalize`` is ``True``, ``.py`` files are fingerprinted by their
+    docstring-stripped AST and env files by their byte content, so the result is
+    invariant to docstrings, comments, formatting, and mtime-only changes.
+
     Args:
         path (str): The root directory to scan.
+        normalize (bool): Use AST/content fingerprints instead of size+mtime.
 
     Returns:
         list[str]: A signature string for each ``.py`` file found.
@@ -41,7 +74,6 @@ def get_sigs(path: str):
         >>> get_sigs('/tmp/project')
         ['/tmp/project/main.py:1024:1680000000.0', ...]
     """
-    _ENV_FILES = {".python-version", "pyproject.toml", "uv.lock"}
     items = []
     with os.scandir(path) as entries:
         for entry in entries:
@@ -50,27 +82,35 @@ def get_sigs(path: str):
             if entry.is_file(follow_symlinks=False) and (
                 entry.name.endswith(".py") or entry.name in _ENV_FILES
             ):
-                stat_info = entry.stat(follow_symlinks=False)
-                items.append(f"{entry.path}:{stat_info.st_size}:{stat_info.st_mtime}")
-            if entry.is_dir(follow_symlinks=False) and entry.name not in [
-                ".venv",
-                "venv",
-                "__pycache__",
-                ".git",
-            ]:
-                items.extend(get_sigs(entry.path))
+                if normalize:
+                    if entry.name.endswith(".py"):
+                        items.append(_normalized_sig(entry.path))
+                    else:
+                        items.append(_byte_sig(entry.path))
+                else:
+                    stat_info = entry.stat(follow_symlinks=False)
+                    items.append(
+                        f"{entry.path}:{stat_info.st_size}:{stat_info.st_mtime}"
+                    )
+            if entry.is_dir(follow_symlinks=False) and entry.name not in _SKIP_DIRS:
+                items.extend(get_sigs(entry.path, normalize=normalize))
     return items
 
 
-def get_context_hash(path: str) -> str:
+def get_context_hash(path: str, *, normalize: bool = False) -> str:
     """Compute an MD5 hash that uniquely identifies a file or directory.
 
     The hash is derived from a signature string. For a file, the signature consists of
     its path, size, and modification time. For a directory, the signature is the
     concatenation of the signatures of all files within it (recursively).
 
+    When ``normalize`` is ``True`` the signatures are derived from each ``.py``
+    file's docstring-stripped AST, making the hash invariant to docstrings,
+    comments, formatting, and mtime-only changes.
+
     Args:
         path (str): The filesystem path to hash.
+        normalize (bool): Use AST/content fingerprints instead of size+mtime.
 
     Returns:
         str: The hexadecimal MD5 digest.
@@ -84,10 +124,13 @@ def get_context_hash(path: str) -> str:
     """
     h = hashlib.md5()  # nosec
     if os.path.isfile(path):
-        s = os.stat(path)
-        h.update(f"{path}:{s.st_size}:{s.st_mtime}".encode())
+        if normalize and path.endswith(".py"):
+            h.update(_normalized_sig(path).encode())
+        else:
+            s = os.stat(path)
+            h.update(f"{path}:{s.st_size}:{s.st_mtime}".encode())
     elif os.path.isdir(path):
-        for sig in sorted(get_sigs(path)):
+        for sig in sorted(get_sigs(path, normalize=normalize)):
             h.update(sig.encode())
     else:
         h.update(b"empty")

py_cq/execution_engine.py

@@ -16,9 +16,11 @@ import logging
 import os
 import shlex
 import shutil
+import signal
 import subprocess
 import sys
 import tempfile
+import threading
 import time
 from collections.abc import Collection
 from concurrent.futures import ThreadPoolExecutor, as_completed
@@ -102,6 +104,80 @@ def _build_exclude_str(
     return "".join(parts)
 
 
+def _terminate_process_tree(proc: "subprocess.Popen") -> None:
+    """Best-effort kill of a shell subprocess and all its children, cross-platform.
+
+    ``shell=True`` spawns a shell that spawns ``uv``/``python``, so killing the
+    immediate child is not enough - the whole tree must go.
+    """
+    if proc.poll() is not None:
+        return
+    if sys.platform == "win32":
+        subprocess.run(
+            ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+            capture_output=True,
+            check=False,
+        )  # nosec
+    else:
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+        except (ProcessLookupError, PermissionError):
+            proc.kill()
+
+
+def _run_command(
+    command: str, run_env: dict, cancel_event: threading.Event | None
+) -> tuple[str, str, int, bool]:
+    """Run *command* in a shell and return ``(stdout, stderr, returncode, cancelled)``.
+
+    When *cancel_event* fires mid-run the process tree is terminated and
+    ``cancelled`` is True (captured output is discarded). With no event this is
+    a plain blocking ``subprocess.run`` (no poll overhead for the common path).
+    """
+    if cancel_event is None:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            shell=True,
+            encoding="utf-8",
+            errors="replace",
+            env=run_env,
+            check=False,
+        )  # nosec
+        return result.stdout, result.stderr, result.returncode, False
+    if cancel_event.is_set():
+        return "", "", -1, True
+    popen_kwargs: dict[str, Any] = {}
+    if sys.platform != "win32":
+        # New session/process group so os.killpg reaches the shell's children.
+        popen_kwargs["start_new_session"] = True
+    proc = subprocess.Popen(
+        command,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        shell=True,
+        encoding="utf-8",
+        errors="replace",
+        env=run_env,
+        **popen_kwargs,
+    )  # nosec
+    # Poll so a cancel signal can terminate a still-running command.
+    while True:
+        try:
+            stdout, stderr = proc.communicate(timeout=0.1)
+            return stdout, stderr, proc.returncode, False
+        except subprocess.TimeoutExpired:
+            if cancel_event.is_set():
+                _terminate_process_tree(proc)
+                try:
+                    proc.communicate(timeout=5)
+                except subprocess.TimeoutExpired:  # pragma: no cover
+                    proc.kill()
+                return "", "", proc.returncode or -1, True
+
+
 def run_tool(
     tool_config: ToolConfig,
     context_path: str,
@@ -109,6 +185,7 @@ def run_tool(
     *,
     precomputed_hash: str | None = None,
     project_tag: str | None = None,
+    cancel_event: threading.Event | None = None,
 ) -> RawResult:
     """Runs a tool defined by its configuration and returns the execution result.
 
@@ -195,11 +272,12 @@ def run_tool(
         python=python,
         exclude=exclude,
     )
-    context_hash = (
-        precomputed_hash
-        if precomputed_hash is not None
-        else get_context_hash(context_path)
-    )
+    if precomputed_hash is not None:
+        context_hash = precomputed_hash
+    elif tool_config.cache_invariant == "ast":
+        context_hash = get_context_hash(context_path, normalize=True)
+    else:
+        context_hash = get_context_hash(context_path)
     cache_key = f"{command}:{context_hash}"
 
     t_cache0 = time.perf_counter()
@@ -223,18 +301,20 @@ def run_tool(
     run_env["COVERAGE_FILE"] = coverage_tmp
     t_sub0 = time.perf_counter()
     try:
-        result = subprocess.run(
-            command,
-            capture_output=True,
-            text=True,
-            shell=True,
-            encoding="utf-8",
-            errors="replace",
-            env=run_env,
-        )  # nosec
+        stdout, stderr, return_code, cancelled = _run_command(
+            command, run_env, cancel_event
+        )
     finally:
         Path(coverage_tmp).unlink(missing_ok=True)
     t_sub = time.perf_counter() - t_sub0
+    if cancelled:
+        # A dependency (e.g. pytest) already failed, so this run is moot. Return
+        # an empty result - uncached, since it was terminated, not completed -
+        # and let the parser produce its skip/zero output.
+        log.debug(
+            f"{tool_config.name}: [CANCELLED] {tool_config.skip_if} failed; terminated after {t_sub * 1000:.0f}ms"
+        )
+        return RawResult(tool_name=tool_config.name)
     log.debug(
         f"{tool_config.name}: [MISS] cache={t_cache * 1000:.1f}ms tool={t_sub * 1000:.0f}ms: {command}"
     )
@@ -242,13 +322,15 @@ def run_tool(
     raw_result = RawResult(
         tool_name=tool_config.name,
         command=command,
-        stdout=result.stdout,
-        stderr=result.stderr,
-        return_code=result.returncode,
+        stdout=stdout,
+        stderr=stderr,
+        return_code=return_code,
         timestamp=timestamp,
         project_path=project_dir,
     )
-    _cache.set(cache_key, raw_result.to_dict(), expire=5 * 24 * 60 * 60, tag=project_tag)
+    _cache.set(
+        cache_key, raw_result.to_dict(), expire=5 * 24 * 60 * 60, tag=project_tag
+    )
     return raw_result
 
 
@@ -306,18 +388,42 @@ def run_tools(
     t_hash0 = time.perf_counter()
     root = project_root or str(Path(path).resolve())
     shared_hash = get_context_hash(root)
-    log.debug(f"context_hash: {(time.perf_counter() - t_hash0) * 1000:.1f}ms {shared_hash}")
+    log.debug(
+        f"context_hash: {(time.perf_counter() - t_hash0) * 1000:.1f}ms {shared_hash}"
+    )
 
-    sentinel_key = f"_project_hash:{root}"
-    prev_hash = _cache.get(sentinel_key)
-    if prev_hash is not None and prev_hash != shared_hash:
-        evicted = _cache.evict(root)
-        log.debug(f"project changed: evicted {evicted} stale cache entries for {root}")
-    _cache.set(sentinel_key, shared_hash, expire=5 * 24 * 60 * 60, tag=root)
+    # Cache keys are content-based, so a changed project naturally produces new
+    # keys; stale entries age out via TTL + size_limit (no blanket eviction).
+    # Tools flagged cache_invariant="ast" key on the docstring-stripped AST so
+    # docstring/comment/format-only edits stay cache hits. Compute it once here
+    # (not lazily in the worker threads, where pytest and coverage would race
+    # and each re-parse the whole tree) and only when some tool needs it.
+    norm_hash = shared_hash
+    if any(tc.cache_invariant == "ast" for tc in tool_configs):
+        t_norm0 = time.perf_counter()
+        norm_hash = get_context_hash(root, normalize=True)
+        log.debug(
+            f"context_hash(ast): {(time.perf_counter() - t_norm0) * 1000:.1f}ms {norm_hash}"
+        )
+
+    def _hash_for(tool_config: ToolConfig) -> str:
+        return norm_hash if tool_config.cache_invariant == "ast" else shared_hash
 
-    def _run_and_parse(tool_config: ToolConfig) -> tuple[int, ToolResult]:
+    def _run_and_parse(
+        tool_config: ToolConfig, cancel_event: threading.Event | None = None
+    ) -> tuple[int, ToolResult]:
         t0 = time.perf_counter()
-        raw_result = run_tool(tool_config, path, excludes, precomputed_hash=shared_hash, project_tag=root)
+        # Only pass cancel_event when present so patched run_tool stubs in tests
+        # (which don't declare the kwarg) keep working for non-cancellable tools.
+        extra = {"cancel_event": cancel_event} if cancel_event is not None else {}
+        raw_result = run_tool(
+            tool_config,
+            path,
+            excludes,
+            precomputed_hash=_hash_for(tool_config),
+            project_tag=root,
+            **extra,
+        )
         tr = tool_config.parser_class(tool_config.parser_config).parse(raw_result)
         tr.duration_s = time.perf_counter() - t0
         return tool_config.order, tr
@@ -329,8 +435,10 @@ def run_tools(
         for i, tool_config in enumerate(sorted_configs):
             try:
                 prioritized.append(_run_and_parse(tool_config))
-            except Exception as exc:
-                log.error(f"{tool_config.name} generated an exception: {exc} {exc.__traceback__}")
+            except Exception as exc:  # noqa: BLE001 - a crashing tool must not abort the run
+                log.error(
+                    f"{tool_config.name} generated an exception: {exc} {exc.__traceback__}"
+                )
                 n_skipped = n_total - i - 1
                 if n_skipped:
                     remaining = ", ".join(tc.name for tc in sorted_configs[i + 1 :])
@@ -357,52 +465,55 @@ def run_tools(
         return [tr for _, tr in sorted(prioritized)]
     configs_by_name = {tc.name: tc for tc in tool_configs}
 
-    def _run_if_dep_passed(dep_future, tool_config: ToolConfig, dep_config: ToolConfig) -> tuple[int, ToolResult]:
-        # Wait for the dependency within the same thread pool - no phase split,
-        # so all other tools keep running in parallel while we block here.
-        try:
-            _, dep_tr = dep_future.result()
-        except Exception:
-            return _run_and_parse(tool_config)
-        if dep_tr.metrics and min(dep_tr.metrics.values()) < dep_config.error_threshold:
-            # Dependency failed its error threshold: skip this tool and return a
-            # synthetic empty result. Coverage declares skip_if = "pytest" so that
-            # it never re-invokes pytest (which the coverage command does internally)
-            # when we already know pytest is broken.
-            log.debug(f"{tool_config.name}: skipping because {tool_config.skip_if} failed")
-            t0 = time.perf_counter()
-            tr = tool_config.parser_class(tool_config.parser_config).parse(
-                RawResult(tool_name=tool_config.name)
-            )
-            tr.duration_s = time.perf_counter() - t0
-            return tool_config.order, tr
-        return _run_and_parse(tool_config)
-
     timings: list[tuple[int, str, float]] = []
-    # Sort by order so that when we build name_to_future below, a dependency's
-    # future is always registered before the tool that declares skip_if on it.
     sorted_configs = sorted(tool_configs, key=lambda tc: tc.order)
+    # A tool with skip_if gets a cancel event: it runs in parallel with its
+    # dependency, and is terminated mid-run only if that dependency *fails* its
+    # error threshold. Coverage declares skip_if = "pytest" so a broken pytest
+    # kills the coverage run (which re-invokes pytest internally) instead of
+    # letting it finish a pointless second suite execution.
+    cancel_events = {
+        tc.name: threading.Event()
+        for tc in sorted_configs
+        if tc.skip_if and tc.skip_if in configs_by_name
+    }
     name_to_future: dict[str, Any] = {}
     with ThreadPoolExecutor(max_workers=max_workers or len(tool_configs)) as executor:
         future_to_tool = {}
         for tc in sorted_configs:
-            dep_name = tc.skip_if
-            dep_future = name_to_future.get(dep_name) if dep_name else None
-            dep_config = configs_by_name.get(dep_name) if dep_name else None
-            if dep_future and dep_config:
-                # Submit a wrapper that waits on the dependency future first.
-                f = executor.submit(_run_if_dep_passed, dep_future, tc, dep_config)
-            else:
-                f = executor.submit(_run_and_parse, tc)
+            f = executor.submit(_run_and_parse, tc, cancel_events.get(tc.name))
             future_to_tool[f] = tc
             name_to_future[tc.name] = f
+
+        def _cancel_on_dep_failure(
+            dep_future, ev: threading.Event, dep_config: ToolConfig, name: str
+        ) -> None:
+            try:
+                _, dep_tr = dep_future.result()
+            except Exception:  # noqa: BLE001 - a crashed dep cancels nothing
+                return
+            if (
+                dep_tr.metrics
+                and min(dep_tr.metrics.values()) < dep_config.error_threshold
+            ):
+                log.debug(f"{name}: cancelling because {dep_config.name} failed")
+                ev.set()
+
+        for tc in sorted_configs:
+            if tc.name in cancel_events:
+                dep_config = configs_by_name[tc.skip_if]
+                name_to_future[tc.skip_if].add_done_callback(
+                    lambda fut, ev=cancel_events[tc.name], dc=dep_config, nm=tc.name: (
+                        _cancel_on_dep_failure(fut, ev, dc, nm)
+                    )
+                )
         for future in as_completed(future_to_tool):
             tool_config = future_to_tool[future]
             try:
                 tc_order, tr = future.result()
                 prioritized.append((tc_order, tr))
                 timings.append((tc_order, tool_config.name, tr.duration_s))
-            except Exception as exc:
+            except Exception as exc:  # noqa: BLE001 - a crashing tool must not abort the run
                 log.error(f"{tool_config.name} generated an exception: {exc}")
     per_tool = ", ".join(f"{name}={dur:.2f}s" for _, name, dur in sorted(timings))
     log.debug(f"run_tools elapsed: {time.perf_counter() - t_start:.2f}s [{per_tool}]")

py_cq/localtypes.py

@@ -60,8 +60,11 @@ class ToolConfig:
         default_factory=list
     )  # Top-level dir/file names to omit from {scan_targets}
     skip_for_file: bool = False  # If True, skip when context_path is a single file
-    gate_strict: bool = True  # If False, small regressions above warning_threshold are accepted
+    gate_strict: bool = (
+        True  # If False, small regressions above warning_threshold are accepted
+    )
     skip_if: str = ""  # Tool name; if that tool's score is below its error_threshold, skip this tool
+    cache_invariant: str = ""  # "ast": key the cache on the docstring-stripped AST, ignoring docstrings/comments/format
 
 
 @dataclass
@@ -172,7 +175,6 @@ class AbstractParser(ABC):
     @abstractmethod
     def parse(self, raw_result: RawResult) -> ToolResult:
         """Converts raw tool output into a structured ToolResult."""
-        pass
 
     def format_llm_message(
         self, tr: ToolResult, *, context_lines: int = 15, limit: int = 1

py_cq/parsers/common.py

@@ -47,11 +47,7 @@ def format_source_context(
     error_offset = line - context_start  # 0-based index of the error line in raw_lines
     collected = []
     for i, rline in enumerate(raw_lines):
-        if i > error_offset and (
-            rline.startswith("def ")
-            or rline.startswith("async def ")
-            or rline.startswith("class ")
-        ):
+        if i > error_offset and (rline.startswith(("def ", "async def ", "class "))):
             break
         collected.append(f"{context_start + i}: {rline}")
     src = "\n".join(collected)
@@ -382,8 +378,7 @@ def score_logistic_variant(
         1.0
         >>> score_logistic_variant(10, scale_factor=0)
         0.0"""
-    if errors < 0:
-        errors = 0
+    errors = max(errors, 0)
     if scale_factor == 0:
         return 1.0 if errors == 0 else 0.0
     try: