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

py_cq/execution_engine.py

@@ -13,9 +13,12 @@ where tool invocations may be expensive and should be avoided
 when a cached result already exists."""
 
 import logging
+import os
+import shlex
 import shutil
 import subprocess
 import sys
+import tempfile
 import time
 from collections.abc import Collection
 from concurrent.futures import ThreadPoolExecutor, as_completed
@@ -29,7 +32,9 @@ from py_cq.localtypes import RawResult, ToolConfig, ToolResult
 
 log = logging.getLogger("cq")
 
-_cache = Cache(Path.home() / ".cache" / "cq", size_limit=100 * 1024 * 1024, disk=JSONDisk)
+_cache = Cache(
+    Path.home() / ".cache" / "cq", size_limit=100 * 1024 * 1024, disk=JSONDisk
+)
 
 
 def _find_project_root(path: Path) -> Path | None:
@@ -53,17 +58,58 @@ def _dep_in_venv(dep: str, project_root: Path) -> bool:
     return False
 
 
-def _build_exclude_str(exclude_format: str, excludes: list[str], **extra_vars: str) -> str:
+def _compute_scan_targets(
+    context_path: str,
+    scan_exclude_names: list[str],
+    user_excludes: list[str] | None = None,
+) -> str:
+    """Return space-separated quoted absolute paths for bandit-style scanning.
+
+    When context_path is a directory, enumerates its top-level children and
+    omits any whose name is in scan_exclude_names or user_excludes.  When it's
+    a file, returns just that file.  Falls back to the root itself if all
+    children are excluded.
+    """
+    root = Path(context_path).resolve()
+    if not root.is_dir():
+        return f'"{root}"'
+    excluded = set(scan_exclude_names) | {Path(e).name for e in (user_excludes or [])}
+    targets = [str(p) for p in sorted(root.iterdir()) if p.name not in excluded]
+    paths = targets if targets else [str(root)]
+    return " ".join(f'"{p}"' for p in paths)
+
+
+def _build_exclude_str(
+    exclude_format: str, excludes: list[str], **extra_vars: str
+) -> str:
+    """Builds an exclude string from a list of excludes and a format string."""
+
     if not exclude_format or not excludes:
         return ""
     parts = []
     for exc in excludes:
         abs_posix_path = Path(exc).resolve().as_posix()
-        parts.append(exclude_format.format(path=exc, abs_posix_path=abs_posix_path, **extra_vars))
+        abs_native_path = str(Path(exc).resolve())
+        # shlex.quote prevents shell injection via exclude paths
+        parts.append(
+            exclude_format.format(
+                path=shlex.quote(exc),
+                abs_posix_path=shlex.quote(abs_posix_path),
+                abs_native_path=shlex.quote(abs_native_path),
+                **{k: shlex.quote(v) for k, v in extra_vars.items()},
+            )
+        )
     return "".join(parts)
 
 
-def run_tool(tool_config: ToolConfig, context_path: str, excludes: list[str] | None = None) -> RawResult:
+def run_tool(
+    tool_config: ToolConfig,
+    context_path: str,
+    excludes: list[str] | None = None,
+    *,
+    precomputed_hash: str | None = None,
+    project_tag: str | None = None,
+) -> RawResult:
     """Runs a tool defined by its configuration and returns the execution result.
 
     Args:
@@ -83,6 +129,8 @@ def run_tool(tool_config: ToolConfig, context_path: str, excludes: list[str] | N
         0"""
     python = sys.executable
     path = str(Path(context_path))
+    run_env = None
+    project_dir = ""
     if tool_config.run_in_target_env:
         uv = shutil.which("uv")
         if uv:
@@ -94,21 +142,102 @@ def run_tool(tool_config: ToolConfig, context_path: str, excludes: list[str] | N
                 project_root = _find_project_root(resolved)
                 abs_dir = str(project_root) if project_root else str(resolved.parent)
                 path = str(resolved)
+            project_dir = Path(abs_dir).as_posix()
             project_root_path = Path(abs_dir)
-            missing_deps = [d for d in tool_config.extra_deps if not _dep_in_venv(d, project_root_path)]
-            with_flags = " ".join(f"--with {dep}" for dep in missing_deps)
+            missing_deps = [
+                d
+                for d in tool_config.extra_deps
+                if not _dep_in_venv(d, project_root_path)
+            ]
+            # Quote deps with shlex.quote to prevent injection via extra_deps.
+            # The uv path and abs_dir use standard double-quoting which is
+            # compatible with both POSIX and MSYS bash on Windows.
+            with_flags = " ".join(f"--with {shlex.quote(dep)}" for dep in missing_deps)
             no_sync = "--no-sync" if sys.executable.startswith(abs_dir) else ""
-            python = f'"{uv}" run {no_sync} --directory "{abs_dir}" {with_flags}'.strip()
+            python = (
+                f'"{uv}" run {no_sync} --directory "{abs_dir}" {with_flags}'.strip()
+            )
+            # Strip venv env vars so the target project's environment is used cleanly.
+            # VIRTUAL_ENV pointing to cq's own venv would cause uv to warn and can
+            # corrupt the subprocess's sys.path, mixing packages from both projects.
+            run_env = {
+                k: v
+                for k, v in os.environ.items()
+                if k not in ("VIRTUAL_ENV", "PYTHONHOME", "PYTHONPATH")
+            }
     abs_context_path = str(Path(context_path).resolve())
+    abs_context_path_posix = Path(context_path).resolve().as_posix()
+    native_sep = os.sep
+    if not project_dir:
+        project_dir = (
+            Path(abs_context_path).as_posix()
+            if Path(abs_context_path).is_dir()
+            else Path(abs_context_path).parent.as_posix()
+        )
     input_path_posix = Path(context_path).as_posix().rstrip("/")
-    exclude = _build_exclude_str(tool_config.exclude_format, excludes or [], input_path_posix=input_path_posix)
-    command = tool_config.command.format(context_path=path, abs_context_path=abs_context_path, input_path_posix=input_path_posix, python=python, exclude=exclude)
-    cache_key = f"{command}:{get_context_hash(context_path)}"
-    if cache_key in _cache:
-        log.info(f"Cache hit: {command}")
-        return RawResult(**cast(dict[str, Any], _cache[cache_key]))
-    log.info(f"Running: {command}")
-    result = subprocess.run(command, capture_output=True, text=True, shell=True, encoding="utf-8", errors="replace") # nosec
+    exclude = _build_exclude_str(
+        tool_config.exclude_format,
+        excludes or [],
+        input_path_posix=input_path_posix,
+        abs_context_path_posix=abs_context_path_posix,
+    )
+    scan_targets = _compute_scan_targets(
+        context_path, tool_config.scan_exclude_names, excludes
+    )
+
+    command = tool_config.command.format(
+        context_path=path,
+        abs_context_path=abs_context_path,
+        abs_context_path_posix=abs_context_path_posix,
+        input_path_posix=input_path_posix,
+        native_sep=native_sep,
+        scan_targets=scan_targets,
+        python=python,
+        exclude=exclude,
+    )
+    context_hash = (
+        precomputed_hash
+        if precomputed_hash is not None
+        else get_context_hash(context_path)
+    )
+    cache_key = f"{command}:{context_hash}"
+
+    t_cache0 = time.perf_counter()
+    cached = _cache.get(cache_key)
+    t_cache = time.perf_counter() - t_cache0
+    if cached is not None:
+        log.debug(
+            f"{tool_config.name}: [CACHE HIT] cache={t_cache * 1000:.1f}ms {command}"
+        )
+        return RawResult(**cast(dict[str, Any], cached))
+
+    # shell=True is required because commands use shell features (&&, |) and
+    # variable substitution ({python} expands to a compound uv command).
+    # All user-supplied values (context_path, excludes) are properly quoted
+    # via shlex.quote() to prevent injection - see _build_exclude_str and
+    # the uv command assembly above.
+    if run_env is None:
+        run_env = dict(os.environ)
+    _fd, coverage_tmp = tempfile.mkstemp(prefix=".coverage.cq.")
+    os.close(_fd)
+    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
+    finally:
+        Path(coverage_tmp).unlink(missing_ok=True)
+    t_sub = time.perf_counter() - t_sub0
+    log.debug(
+        f"{tool_config.name}: [MISS] cache={t_cache * 1000:.1f}ms tool={t_sub * 1000:.0f}ms: {command}"
+    )
     timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
     raw_result = RawResult(
         tool_name=tool_config.name,
@@ -117,12 +246,20 @@ def run_tool(tool_config: ToolConfig, context_path: str, excludes: list[str] | N
         stderr=result.stderr,
         return_code=result.returncode,
         timestamp=timestamp,
+        project_path=project_dir,
     )
-    _cache.set(cache_key, raw_result.to_dict(), expire=5 * 24 * 60 * 60)
+    _cache.set(cache_key, raw_result.to_dict(), expire=5 * 24 * 60 * 60, tag=project_tag)
     return raw_result
 
 
-def run_tools(tool_configs: Collection[ToolConfig], path: str, max_workers: int = 0, early_exit: bool = False, excludes: list[str] | None = None) -> list[ToolResult]:
+def run_tools(
+    tool_configs: Collection[ToolConfig],
+    path: str,
+    max_workers: int = 0,
+    early_exit: bool = False,
+    excludes: list[str] | None = None,
+    project_root: str | None = None,
+) -> list[ToolResult]:
     """Run multiple tools and return their parsed results.
 
     Runs each tool specified in *tool_configs* on the file or directory at
@@ -162,39 +299,67 @@ def run_tools(tool_configs: Collection[ToolConfig], path: str, max_workers: int
         ...     ToolConfig(name='scan', parser_class=ScanParser),
         ... ]
         >>> results = run_tools(configs, '/path/to/project', parallel=True)"""
+    if not tool_configs:
+        return []
+    t_start = time.perf_counter()
+    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}")
+
+    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]:
         t0 = time.perf_counter()
-        raw_result = run_tool(tool_config, path, excludes)
+        raw_result = run_tool(tool_config, path, excludes, precomputed_hash=shared_hash, project_tag=root)
         tr = tool_config.parser_class(tool_config.parser_config).parse(raw_result)
         tr.duration_s = time.perf_counter() - t0
         return tool_config.order, tr
 
-    if not tool_configs:
-        return []
-    t_start = time.perf_counter()
     prioritized: list[tuple[int, ToolResult]] = []
     if early_exit:
-        for tool_config in sorted(tool_configs, key=lambda tc: tc.order):
+        sorted_configs = sorted(tool_configs, key=lambda tc: tc.order)
+        n_total = len(sorted_configs)
+        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}")
+                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 :])
+                    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:
+                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}"
+                    )
                 break
-        log.info(f"run_tools elapsed: {time.perf_counter() - t_start:.2f}s")
+        log.info(f"cq run_tools elapsed: {time.perf_counter() - t_start:.2f}s")
         return [tr for _, tr in sorted(prioritized)]
     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]] = []
         for future in as_completed(future_to_tool):
             tool_config = future_to_tool[future]
             try:
-                prioritized.append(future.result())
+                order, tr = future.result()
+                prioritized.append((order, tr))
+                timings.append((order, tool_config.name, tr.duration_s))
             except Exception as exc:
                 log.error(f"{tool_config.name} generated an exception: {exc}")
-    log.info(f"run_tools elapsed: {time.perf_counter() - t_start:.2f}s")
+    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}]")
     return [tr for _, tr in sorted(prioritized)]

py_cq/language_detector.py

@@ -4,7 +4,10 @@ from pathlib import Path
 
 # Ordered: first match wins. Python is listed first so it takes priority.
 _MARKERS: list[tuple[str, list[str]]] = [
-    ("python", ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile"]),
+    (
+        "python",
+        ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile"],
+    ),
     ("typescript", ["tsconfig.json", "package.json"]),
     ("rust", ["Cargo.toml"]),
     ("go", ["go.mod"]),

py_cq/llm_formatter.py

@@ -1,8 +1,10 @@
 """Format the most important code quality defect as a markdown prompt for LLM consumption."""
 
 import sys
+from pathlib import Path
+from typing import cast
 
-from py_cq.localtypes import CombinedToolResults, ToolConfig
+from py_cq.localtypes import CombinedToolResults, Fingerprint, ToolConfig, ToolResult
 
 
 def _severity(score: float, config: ToolConfig) -> int:
@@ -14,19 +16,91 @@ def _severity(score: float, config: ToolConfig) -> int:
     return 2
 
 
-def format_for_llm(
+def _single_issue_slices(
+    tr: ToolResult,
+    limit: int,
+    silence: list[str] | None = None,
+    project_root: Path | None = None,
+) -> list[ToolResult]:
+    """Return up to `limit` ToolResults each containing one issue from tr.details.
+
+    Returns empty list (not [tr]) when silence specs filter out all issues."""
+    silence_set = set(silence or [])
+    slices: list[ToolResult] = []
+    has_list = any(isinstance(v, list) for v in tr.details.values())
+
+    if has_list:
+        for file, issues in tr.details.items():
+            if isinstance(issues, list):
+                for issue in issues:
+                    candidate = ToolResult(
+                        raw=tr.raw,
+                        metrics=tr.metrics,
+                        details={file: [issue]},
+                        project_path=tr.project_path,
+                    )
+                    if (
+                        _fingerprint_from_slice(
+                            tr.raw.tool_name, candidate, project_root
+                        )
+                        in silence_set
+                    ):
+                        continue
+                    slices.append(candidate)
+                if len(slices) >= limit:
+                    break
+    else:
+        # Non-list details: sort so files with failures (pytest-style) come first, then by coverage ascending
+        def _dict_sort_key(v: object) -> tuple[int, float, float]:
+            if not isinstance(v, dict):
+                return (0, 0.0, 1.0)
+            d = cast("dict[str, object]", v)
+            failures = sum(
+                1
+                for val in d.values()
+                if isinstance(val, str) and val in ("FAILED", "ERROR")
+            )
+            cov_val = d.get("coverage", 0)
+            coverage = float(cov_val) if isinstance(cov_val, (int, float, str)) else 0.0
+            sm_val = d.get("smallness", 1.0)
+            smallness = float(sm_val) if isinstance(sm_val, (int, float)) else 1.0
+            return (-failures, coverage, smallness)
+
+        items = sorted(tr.details.items(), key=lambda x: _dict_sort_key(x[1]))
+        for file, data in items:
+            candidate = ToolResult(
+                raw=tr.raw,
+                metrics=tr.metrics,
+                details={file: data},
+                project_path=tr.project_path,
+            )
+            if (
+                _fingerprint_from_slice(tr.raw.tool_name, candidate, project_root)
+                in silence_set
+            ):
+                continue
+            slices.append(candidate)
+            if len(slices) >= limit:
+                break
+    return slices[:limit] or ([] if silence_set else [tr])
+
+
+def _select_top_issue(
     tool_configs: dict,
     combined: CombinedToolResults,
-    cq_invocation: str | None = None,
-    context_lines: int = 15,
-) -> str:
-    """Return a markdown prompt describing the single most important defect."""
+    limit: int,
+    silence: list[str],
+    project_root: Path | None = None,
+):
+    """Return (worst, slices, config, parser) for the top failing tool, or None if all pass."""
     by_name = {tc.name: tc for tc in tool_configs.values()}
-
     failing = sorted(
         [
-            tr for tr in combined.tool_results
-            if tr.metrics and (cfg := by_name.get(tr.raw.tool_name)) and min(tr.metrics.values()) < cfg.warning_threshold
+            tr
+            for tr in combined.tool_results
+            if tr.metrics
+            and (cfg := by_name.get(tr.raw.tool_name))
+            and min(tr.metrics.values()) < cfg.warning_threshold
         ],
         key=lambda tr: (
             _severity(min(tr.metrics.values()), by_name[tr.raw.tool_name]),
@@ -34,15 +108,123 @@ def format_for_llm(
             min(tr.metrics.values()),
         ),
     )
-    if not failing:
+
+    for candidate in failing:
+        slices = _single_issue_slices(candidate, limit, silence, project_root)
+        if slices:
+            config = by_name[candidate.raw.tool_name]
+            return candidate, slices, config, config.parser_class()
+    return None
+
+
+def _build_message(
+    slices, parser, context_lines: int, limit: int, hint: bool, cq_invocation
+) -> str:
+    parts = [
+        parser.format_llm_message(s, context_lines=context_lines, limit=limit)
+        for s in slices
+    ]
+    n = len(parts)
+    close = "Please fix only this issue." if n == 1 else f"Please fix these {n} issues."
+    body = "\n\n---\n\n".join(parts) + f"\n\n{close}"
+    if hint:
+        if cq_invocation is None:
+            cq_invocation = "cq " + " ".join(sys.argv[1:])
+        body += f" After fixing, run `{cq_invocation}` to verify."
+    return body
+
+
+def _fingerprint_from_slice(
+    tool_name: str, tr: ToolResult, project_root: Path | None = None
+) -> str:
+    """Return fingerprint string for a single-issue ToolResult slice."""
+    root = project_root.resolve() if project_root else None
+    project_str = root.as_posix() if root else ""
+    for file, issues in tr.details.items():
+        if root:
+            p = Path(file)
+            resolved = (root / p).resolve() if not p.is_absolute() else p.resolve()
+            try:
+                path_str = resolved.relative_to(root).as_posix()
+            except ValueError:
+                path_str = resolved.as_posix()
+        else:
+            path_str = Path(file).as_posix()
+        if isinstance(issues, list) and issues:
+            first = issues[0]
+            line = str(first.get("line", "")) if isinstance(first, dict) else ""
+            code = first.get("code", "") if isinstance(first, dict) else ""
+            fp = Fingerprint(
+                tool=tool_name, project=project_str, path=path_str, line=line, code=code
+            )
+        elif isinstance(issues, dict):
+            str_vals = [v for v in issues.values() if isinstance(v, str)]
+            if str_vals and all(v not in ("FAILED", "ERROR") for v in str_vals):
+                continue
+            fp = Fingerprint(tool=tool_name, project=project_str, path=path_str)
+        else:
+            fp = Fingerprint(tool=tool_name, project=project_str, path="")
+        return str(fp)
+    return tool_name
+
+
+def format_for_llm(
+    tool_configs: dict,
+    combined: CombinedToolResults,
+    cq_invocation: str | None = None,
+    context_lines: int = 15,
+    hint: bool = False,
+    limit: int = 1,
+    silence: list[str] | None = None,
+    project_root: Path | None = None,
+) -> str:
+    """Return a markdown prompt describing the top `limit` defects from the worst-scoring tool."""
+    result = _select_top_issue(
+        tool_configs, combined, limit, silence or [], project_root
+    )
+    if result is None:
         return f"# No issues found\n\nOverall score: **{combined.score:.3f} / 1.0**"
+    _, slices, _, parser = result
+    return _build_message(slices, parser, context_lines, limit, hint, cq_invocation)
 
-    worst = failing[0]
-    config = by_name[worst.raw.tool_name]
-    defect_md = config.parser_class().format_llm_message(worst, context_lines=context_lines)
-    if cq_invocation is None:
-        cq_invocation = "cq " + " ".join(sys.argv[1:])
-    return (
-        f"{defect_md}\n\n"
-        f"Please fix only this issue. After fixing, run `{cq_invocation}` to verify."
+
+def format_for_llm_json(
+    tool_configs: dict,
+    combined: CombinedToolResults,
+    cq_invocation: str | None = None,
+    context_lines: int = 15,
+    hint: bool = False,
+    limit: int = 1,
+    silence: list[str] | None = None,
+    project_root: Path | None = None,
+) -> dict:
+    """Like format_for_llm but returns a dict with id, file, project, and message for automation use."""
+    message = format_for_llm(
+        tool_configs,
+        combined,
+        cq_invocation,
+        context_lines,
+        hint,
+        limit,
+        silence,
+        project_root,
+    )
+    project = project_root.as_posix() if project_root else None
+    result = _select_top_issue(
+        tool_configs, combined, limit, silence or [], project_root
     )
+    if result is None:
+        return {"id": None, "file": None, "project": project, "message": message}
+    worst, slices, _, _ = result
+    issue_id = _fingerprint_from_slice(worst.raw.tool_name, slices[0], project_root)
+    raw_file = next(iter(slices[0].details), "")
+    if project_root and raw_file:
+        try:
+            file: str | None = (
+                Path(raw_file).resolve().relative_to(project_root).as_posix() or None
+            )
+        except ValueError:
+            file = Path(raw_file).as_posix() or None
+    else:
+        file = Path(raw_file).as_posix() or None
+    return {"id": issue_id, "file": file, "project": project, "message": message}

py_cq/localtypes.py

@@ -8,6 +8,35 @@ from dataclasses import dataclass, field
 from typing import Any
 
 
+@dataclass
+class Fingerprint:
+    """Stable identity for a single reported issue.
+
+    String form: ``tool::project::path[::line[::code]]``  (trailing empty fields omitted).
+    ``project`` is an absolute path; ``path`` is relative to it.
+    """
+
+    tool: str
+    project: str  # absolute path to project root
+    path: str  # path relative to project
+    line: str = ""
+    code: str = ""
+
+    def __str__(self) -> str:
+        parts = [self.tool, self.project, self.path, self.line, self.code]
+        while parts and not parts[-1]:
+            parts.pop()
+        return "::".join(parts)
+
+    @classmethod
+    def from_string(cls, s: str) -> "Fingerprint":
+        parts = s.split("::")
+        parts += [""] * (5 - len(parts))
+        return cls(
+            tool=parts[0], project=parts[1], path=parts[2], line=parts[3], code=parts[4]
+        )
+
+
 @dataclass
 class ToolConfig:
     """Represents the configuration for an analysis tool, including its name, command, parser class, context path, order, and thresholds for warnings and errors."""
@@ -20,9 +49,17 @@ class ToolConfig:
     warning_threshold: float = 0.7  # Yellow warning if below this
     error_threshold: float = 0.5  # Red error if below this
     run_in_target_env: bool = False  # If True, run in target project's env via uv
-    extra_deps: list[str] = field(default_factory=list)  # Extra deps to inject via uv --with
+    extra_deps: list[str] = field(
+        default_factory=list
+    )  # Extra deps to inject via uv --with
     parser_config: dict[str, Any] = field(default_factory=dict)
-    exclude_format: str = ""  # Per-path template for --exclude injection, e.g. " --exclude {path}"
+    exclude_format: str = (
+        ""  # Per-path template for --exclude injection, e.g. " --exclude {path}"
+    )
+    scan_exclude_names: list[str] = field(
+        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
 
 
 @dataclass
@@ -38,6 +75,7 @@ class RawResult:
     stderr: str = ""
     return_code: int = 0
     timestamp: str = ""  # For tracking when the analysis ran
+    project_path: str = ""  # Absolute path to the target project root
 
     def to_dict(self):
         """Returns a dictionary containing the tool name, command, stdout, stderr, return code, and timestamp."""
@@ -48,6 +86,7 @@ class RawResult:
             "stderr": self.stderr,
             "return_code": self.return_code,
             "timestamp": self.timestamp,
+            "project_path": self.project_path,
         }
 
 
@@ -61,10 +100,9 @@ class ToolResult:
     data into a plain dictionary."""
 
     metrics: dict[str, float] = field(default_factory=dict)
-    details: dict[str, Any] = field(
-        default_factory=dict
-    )  # Additional details about the metric
+    details: dict[str, Any] = field(default_factory=dict)
     raw: RawResult = field(default_factory=RawResult)
+    project_path: str = ""
     duration_s: float = 0.0
 
     def __post_init__(self):
@@ -80,6 +118,7 @@ class ToolResult:
             "tool_name": self.raw.tool_name,
             "metrics": self.metrics,
             "details": self.details,
+            "project_path": self.project_path,
             "duration_s": self.duration_s,
         }
 
@@ -102,7 +141,12 @@ class CombinedToolResults:
         self.tool_results = tool_results
         self.path = path
         scored = [tr for tr in tool_results if tr.metrics]
-        self.score = sum(sum(tr.metrics.values()) / len(tr.metrics) for tr in scored) / len(scored) if scored else 0.0
+        self.score = (
+            sum(sum(tr.metrics.values()) / len(tr.metrics) for tr in scored)
+            / len(scored)
+            if scored
+            else 0.0
+        )
 
     score: float = 0.0
     path: str = ""
@@ -129,7 +173,9 @@ class AbstractParser(ABC):
         """Converts raw tool output into a structured ToolResult."""
         pass
 
-    def format_llm_message(self, tr: ToolResult, *, context_lines: int = 15) -> str:
+    def format_llm_message(
+        self, tr: ToolResult, *, context_lines: int = 15, limit: int = 1
+    ) -> str:
         """Return a single-defect description for LLM consumption.
 
         Default implementation reports the worst metric by name and score.

py_cq/parsers/__init__.py

@@ -1 +1 @@
-"""Tool Response parsers"""
+"""Tool Response parsers"""