python-code-quality 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

py_cq/api.py

@@ -148,13 +148,14 @@ class CQ:
         if clear_cache:
             _cache.clear()
 
-    def raw(self, *, early_exit: bool = False) -> 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(),
             str(self.path),
             self._workers,
             early_exit=early_exit,
+            order=order,
             excludes=self._excludes,
         )
 
@@ -168,22 +169,42 @@ class CQ:
         limit: int = 1,
         silence: list[str] | None = None,
         hint: bool = False,
+        order: str = "severity",
     ) -> 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.
+        Stops running tools after the first issue (early_exit) for speed.
+        ``order="phase"`` selects the first issue of the earliest non-clean
+        phase (dependency order); ``"severity"`` (default) selects the most
+        severe issue first.
         """
-        results = self.raw(early_exit=True)
+        _silence = silence or []
+        results = self.raw(early_exit=True, order=order)
         combined = aggregate_metrics(str(self.path), results)
-        return format_for_llm_json(
+        issue = format_for_llm_json(
             self._registry,
             combined,
             context_lines=self._context_lines,
             hint=hint,
             limit=limit,
-            silence=silence or [],
+            silence=_silence,
             project_root=self._project_root,
         )
+        if issue.get("id") is None and _silence:
+            # Early-exit stopped at a phase whose only issues are silenced.
+            # Re-run all tools to surface issues in later phases.
+            results = self.raw(early_exit=False, order=order)
+            combined = aggregate_metrics(str(self.path), results)
+            issue = format_for_llm_json(
+                self._registry,
+                combined,
+                context_lines=self._context_lines,
+                hint=hint,
+                limit=limit,
+                silence=_silence,
+                project_root=self._project_root,
+            )
+        return issue
 
     def is_fixed(self, fingerprint: str) -> bool:
         """Return True if the fingerprinted issue is no longer present.

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
@@ -67,6 +67,13 @@ class OutputMode(str, Enum):
     RAW = "raw"
 
 
+class OrderMode(str, Enum):
+    """Selection order for the top issue in -o llm/llm-json."""
+
+    SEVERITY = "severity"
+    PHASE = "phase"
+
+
 def _version_callback(value: bool) -> None:
     if not value:
         return
@@ -81,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):
@@ -113,7 +120,7 @@ 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",
@@ -153,12 +160,17 @@ 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(  # 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
     path_obj = Path(path)
@@ -174,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
@@ -200,7 +210,7 @@ def check(
 
     is_llm = output in (OutputMode.LLM, OutputMode.LLM_JSON)
     t0 = time.perf_counter()
-    tool_results = cq.raw(early_exit=is_llm)
+    tool_results = cq.raw(early_exit=is_llm, order=order.value)
     total_s = time.perf_counter() - t0
     combined = aggregate_metrics(path, tool_results)
 

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"
@@ -53,43 +55,49 @@ error_threshold = 0.5
 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}"
+exclude_format = ",{path}"
+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"
+exclude_format = " -e {path}"
+parser = "InterrogateParser"
+order = 8
+warning_threshold = 0.8
+error_threshold = 0.5
+
+[python.interrogate.parser_config]
+skip_empty_init = true
 
 [python.radon-cc]
 command = "{python} -m radon cc --json --exclude '.claude/**' \"{context_path}\""
 parser = "ComplexityParser"
-order = 7
+order = 9
+gate_strict = false
 warning_threshold = 0.6
 error_threshold = 0.4
 
 [python.radon-mi]
 command = "{python} -m radon mi -s --json --exclude '.claude/**' \"{context_path}\""
 parser = "MaintainabilityParser"
-order = 8
+order = 10
+gate_strict = false
 warning_threshold = 0.6
 error_threshold = 0.4
 
 [python.radon-hal]
 command = "{python} -m radon hal -f --json --exclude '.claude/**' \"{context_path}\""
 parser = "HalsteadParser"
-order = 9
-warning_threshold = 0.5
-error_threshold = 0.3
-
-[python.vulture]
-command = "{python} -m vulture \"{context_path}\" --min-confidence 80 --exclude .venv,dist,.*_cache,docs,.git,.claude{exclude}"
-exclude_format = ",{path}"
-parser = "VultureParser"
-order = 10
-warning_threshold = 0.9999
-error_threshold = 0.8
-
-[python.interrogate]
-command = "{python} -m interrogate \"{context_path}\" -e .claude{exclude} -v --fail-under 0"
-exclude_format = " -e {path}"
-parser = "InterrogateParser"
 order = 11
-warning_threshold = 0.8
+gate_strict = false
+warning_threshold = 0.35
 error_threshold = 0.3
-
-[python.interrogate.parser_config]
-skip_empty_init = true

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.
@@ -46,28 +79,38 @@ def get_sigs(path: str):
         for entry in entries:
             # Use follow_symlinks=False to prevent cache poisoning from
             # symlinks pointing outside the project tree (M-2)
-            if entry.is_file(follow_symlinks=False) and entry.name.endswith(".py"):
-                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 entry.is_file(follow_symlinks=False) and (
+                entry.name.endswith(".py") or entry.name in _ENV_FILES
+            ):
+                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.
@@ -81,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,9 +322,9 @@ 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,
     )
@@ -257,6 +337,7 @@ def run_tools(
     path: str,
     max_workers: int = 0,
     early_exit: bool = False,
+    order: str = "severity",
     excludes: list[str] | None = None,
     project_root: str | None = None,
 ) -> list[ToolResult]:
@@ -307,16 +388,29 @@ def run_tools(
     shared_hash = get_context_hash(root)
     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)
-
-    def _run_and_parse(tool_config: ToolConfig) -> tuple[int, ToolResult]:
+    # 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, 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
@@ -328,7 +422,7 @@ def run_tools(
         for i, tool_config in enumerate(sorted_configs):
             try:
                 prioritized.append(_run_and_parse(tool_config))
-            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} {exc.__traceback__}")
                 n_skipped = n_total - i - 1
                 if n_skipped:
@@ -336,29 +430,72 @@ def run_tools(
                     log.warning(f"Early exit: skipped {n_skipped} tool(s): {remaining}")
                 break
             _, tr = prioritized[-1]
-            if tr.metrics and min(tr.metrics.values()) < tool_config.error_threshold:
+            # order="phase" stops at the first phase with *any* finding (not
+            # clean), so phase order is absolute and independent of error/warning
+            # threshold tuning; "severity" stops at the first error.
+            threshold = (
+                tool_config.warning_threshold
+                if order == "phase"
+                else tool_config.error_threshold
+            )
+            if tr.metrics and min(tr.metrics.values()) < threshold:
                 n_skipped = n_total - i - 1
                 if n_skipped:
                     remaining = ", ".join(tc.name for tc in sorted_configs[i + 1 :])
                     log.debug(
-                        f"Error threshold hit at {tool_config.name}: skipped {n_skipped} tool(s): {remaining}"
+                        f"{'Not clean' if order == 'phase' else 'Error threshold hit'} at {tool_config.name}: skipped {n_skipped} tool(s): {remaining}"
                     )
                 break
         log.info(f"cq run_tools elapsed: {time.perf_counter() - t_start:.2f}s")
         return [tr for _, tr in sorted(prioritized)]
+    configs_by_name = {tc.name: tc for tc in tool_configs}
+
+    timings: list[tuple[int, str, float]] = []
+    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 = {
-            executor.submit(_run_and_parse, tool_config): tool_config
-            for tool_config in tool_configs
-        }
-        timings: list[tuple[int, str, float]] = []
+        future_to_tool = {}
+        for tc in sorted_configs:
+            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:
-                order, tr = future.result()
-                prioritized.append((order, tr))
-                timings.append((order, tool_config.name, tr.duration_s))
-            except Exception as exc:
+                tc_order, tr = future.result()
+                prioritized.append((tc_order, tr))
+                timings.append((tc_order, tool_config.name, tr.duration_s))
+            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}]")