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

py_cq/localtypes.py

@@ -43,7 +43,7 @@ class ToolConfig:
 
     name: str  # e.g., "pytest", "coverage", "pydocstyle"
     command: str  # The command to execute (can include placeholders)
-    parser_class: Callable  # Name of the parser class to use
+    parser_class: Callable  # The parser class itself (resolved from its name in config)
     context_path: str = ""  # Path to project or file
     order: int = 5  # 1=first (compilation), 11=last (style)
     warning_threshold: float = 0.7  # Yellow warning if below this
@@ -60,6 +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
+    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
@@ -123,10 +128,12 @@ class ToolResult:
         }
 
 
-@dataclass
 class CombinedToolResults:
     """Aggregates results from multiple tools, stores the associated path, and calculates an overall score by averaging the mean metric values of each ``ToolResult``. If a ``ToolResult`` has no metrics, it contributes zero, and the score defaults to ``0.0`` when the list is empty."""
 
+    score: float
+    path: str
+
     def __init__(self, path: str, tool_results: list[ToolResult]):
         """Initializes a CombinedToolResults instance.
 
@@ -148,9 +155,6 @@ class CombinedToolResults:
             else 0.0
         )
 
-    score: float = 0.0
-    path: str = ""
-
     def to_dict(self) -> dict:
         """Returns a dictionary containing the path, overall score, and each ToolResult serialized."""
         return {
@@ -163,7 +167,7 @@ class CombinedToolResults:
 class AbstractParser(ABC):
     """Base class for parsers that transform raw tool output into structured `ToolResult` objects.
 
-    Subclasses must implement `parse` to convert a `RawResult` into a `ToolResult`. An optional `provide_help` can be overridden to supply contextual guidance for a parsed result."""
+    Subclasses must implement `parse` to convert a `RawResult` into a `ToolResult`. The `format_llm_message` method can be overridden to supply a richer single-defect description for a parsed result."""
 
     def __init__(self, parser_config: dict | None = None):
         self.parser_config = parser_config or {}
@@ -171,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

@@ -1,16 +1,18 @@
-"""Utility functions for normalising numeric values and scoring error magnitudes.
-
-This module provides two small helpers that are often used when working with
-performance metrics or error scores:
-
-* :func:`inv_normalize` - Inversely normalises a value relative to a maximum
-  reference, yielding a float in the interval [0,\u202f1].
-* :func:`score_logistic_variant` - Maps an error magnitude to a bounded score
-  using a logistic-style curve, with optional parameters controlling the scale
-  and steepness of the transition.
-
-Both functions return a float and can be used directly in downstream analytics,
-visualisation or decision-making pipelines."""
+"""Shared helpers used across parsers and the LLM formatter.
+
+This module groups small utilities for several concerns:
+
+* Scoring - :func:`inv_normalize` and :func:`score_logistic_variant` map error
+  magnitudes to bounded ``[0, 1]`` scores.
+* Source context - :func:`read_source_lines`, :func:`format_source_context`,
+  :func:`find_function_source`, :func:`find_enclosing_function`, and
+  :func:`enclosing_function_range` extract fenced code snippets for LLM prompts.
+* Project navigation - :func:`find_in_project`, :func:`format_callee_context`,
+  :func:`extract_callee_name`, :func:`resolve_path`, and :func:`_relative_path`
+  locate and reference definitions across a project tree.
+* Output formatting - :func:`format_issue_header` builds issue headers.
+* Parsing - :func:`parse_json_dict` and :func:`extract_first_issue` read tool
+  output into Python structures."""
 
 import json
 import re
@@ -46,9 +48,7 @@ def format_source_context(
     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 ")
+            rline.startswith(("def ", "async def ", "class "))
         ):
             break
         collected.append(f"{context_start + i}: {rline}")
@@ -380,8 +380,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:

py_cq/parsers/complexityparser.py

@@ -74,6 +74,8 @@ class ComplexityParser(AbstractParser):
         num_items = 0
         max_complexity = 30
         for file, functions in data.items():
+            if not isinstance(functions, list):
+                continue
             file_name = file.replace("\\", "/")
             if file_name not in tr.details:
                 tr.details[file_name] = {}

py_cq/parsers/coverageparser.py

@@ -1,11 +1,11 @@
 """Parses raw coverage tool output into structured ToolResult instances with per-function granularity."""
 
-import ast
 import logging
 from pathlib import Path
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
 from py_cq.parsers.common import find_function_source, resolve_path
+from py_cq.source_file import get_source
 
 log = logging.getLogger("cq")
 
@@ -29,30 +29,19 @@ def _parse_line_ranges(s: str) -> set[int]:
     return result
 
 
-def _get_signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
-    """Return the signature of the function definition as a string."""
-    prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
-    args = ast.unparse(node.args)
-    returns = f" -> {ast.unparse(node.returns)}" if node.returns else ""
-    return f"{prefix} {node.name}({args}){returns}"
-
-
 def _extract_functions(file: str, missing_lines_str: str) -> list[tuple[str, int, str]]:
     """Return (name, lineno, signature) for functions whose bodies overlap with the missing line ranges."""
     try:
-        source = Path(file).read_text(encoding="utf-8", errors="replace")
-        tree = ast.parse(source)
-    except (OSError, SyntaxError, ValueError):
+        funcs = get_source(file).functions
+    except OSError:
         return []
     missing = _parse_line_ranges(missing_lines_str)
     seen: set[str] = set()
     result: list[tuple[str, int, str]] = []
-    for node in sorted(ast.walk(tree), key=lambda n: getattr(n, "lineno", 0)):
-        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            end = getattr(node, "end_lineno", node.lineno)
-            if missing & set(range(node.lineno, end + 1)) and node.name not in seen:
-                seen.add(node.name)
-                result.append((node.name, node.lineno, _get_signature(node)))
+    for fn in funcs:
+        if missing & set(range(fn.lineno, fn.end_lineno + 1)) and fn.name not in seen:
+            seen.add(fn.name)
+            result.append((fn.name, fn.lineno, fn.signature))
     return result
 
 
@@ -146,6 +135,8 @@ class CoverageParser(AbstractParser):
             ]
 
         tr.details = details
+        if "coverage" not in tr.metrics:
+            tr.metrics["coverage"] = 0.0
         return tr
 
     def format_llm_message(
@@ -199,4 +190,6 @@ class CoverageParser(AbstractParser):
                 parts.append(f"\nAdd tests to: {location}")
 
             return "\n".join(parts)
+        if tr.metrics.get("coverage", 1.0) == 0.0:
+            return "**Coverage: 0%** - pytest failed or collected no tests, so no coverage data is available."
         return ""

py_cq/parsers/halsteadparser.py

@@ -83,11 +83,12 @@ class HalsteadParser(AbstractParser):
                     "functions": {},
                 }
             if "error" in values:
+                tr.details[file_name]["error"] = values["error"]
                 min_file_nb = 0.0
                 min_file_sm = 0.0
                 min_function_nb = 0.0
                 min_function_sm = 0.0
-                tr.details[file_name]["error"] = values["error"]
+                continue
             if "total" in values:
                 nb, sm = self.extract_bugs_and_volume(
                     values.get("total", {}), MAX_FILE_BUGS, MAX_FILE_VOLUME
@@ -106,7 +107,7 @@ class HalsteadParser(AbstractParser):
                     min_function_nb = min(nb, min_function_nb)
                     min_function_sm = min(sm, min_function_sm)
                     tr.details[file_name]["functions"][function] = {
-                        "no_bugs": nb,
+                        "bug_free": nb,
                         "smallness": sm,
                         "bugs": function_values.get("bugs", 0),
                         "volume": function_values.get("volume", 0),
@@ -141,7 +142,7 @@ class HalsteadParser(AbstractParser):
         for file_name, file_data in tr.details.items():
             if is_function_metric:
                 for func_name, func_data in file_data.get("functions", {}).items():
-                    s = func_data.get("no_bugs" if is_bug_metric else "smallness", 1.0)
+                    s = func_data.get("bug_free" if is_bug_metric else "smallness", 1.0)
                     if s < worst_score:
                         worst_score = s
                         worst_file = file_name

py_cq/parsers/interrogateparser.py

@@ -21,6 +21,7 @@ from py_cq.parsers.common import (
     format_issue_header,
     format_source_context,
 )
+from py_cq.source_file import get_source
 
 _SKIP_PARAMS = {"self", "cls"}
 
@@ -34,9 +35,10 @@ def _format_missing_docstring(file_str: str, line: int, code: str, message: str)
         return base + "\n\nInsert a module-level docstring as the very first statement in the file."
 
     try:
-        source = Path(file_str).read_text(encoding="utf-8")
-        tree = ast.parse(source)
-    except (OSError, SyntaxError):
+        tree = get_source(file_str).tree
+    except OSError:
+        tree = None
+    if tree is None:
         return base + "\n\nInsert a docstring as the first statement in the body."
 
     for node in ast.walk(tree):
@@ -88,7 +90,7 @@ def _load_interrogate_cfg(context_path: str) -> dict:
             try:
                 data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
                 return data.get("tool", {}).get("interrogate", {})
-            except Exception:
+            except (tomllib.TOMLDecodeError, OSError, UnicodeDecodeError):
                 return {}
     return {}
 
@@ -104,9 +106,7 @@ def _skip_node(name: str, cfg: dict) -> bool:
         return True
     if is_private and cfg.get("ignore-private"):
         return True
-    if is_semiprivate and cfg.get("ignore-semiprivate"):
-        return True
-    return False
+    return bool(is_semiprivate and cfg.get("ignore-semiprivate"))
 
 
 def _missing_docstrings(file_path: Path, cfg: dict | None = None) -> list[tuple[int, str, str]]:
@@ -117,11 +117,13 @@ def _missing_docstrings(file_path: Path, cfg: dict | None = None) -> list[tuple[
     the module.
     """
     try:
-        source = file_path.read_text(encoding="utf-8")
-        tree = ast.parse(source, filename=str(file_path))
-    except (OSError, SyntaxError):
+        sf = get_source(str(file_path))
+        tree = sf.tree
+    except OSError:
         return []
-    src_lines = source.splitlines()
+    if tree is None:
+        return []
+    src_lines = sf.text.splitlines()
 
     def src_line(lineno: int) -> str:
         """Return the stripped content of the source line at the given line number."""
@@ -137,16 +139,13 @@ def _missing_docstrings(file_path: Path, cfg: dict | None = None) -> list[tuple[
 
     effective_cfg = cfg or {}
     results = []
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Module):
-            if not ast.get_docstring(node):
-                results.append((0, "module", first_code_line()))
-        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            if not ast.get_docstring(node) and not _skip_node(node.name, effective_cfg):
-                results.append((node.lineno, "def", src_line(node.lineno)))
-        elif isinstance(node, ast.ClassDef):
-            if not ast.get_docstring(node) and not _skip_node(node.name, effective_cfg):
-                results.append((node.lineno, "class", src_line(node.lineno)))
+    if not sf.module_has_docstring:
+        results.append((0, "module", first_code_line()))
+    for d in sf.definitions:
+        if d.has_docstring or _skip_node(d.name, effective_cfg):
+            continue
+        kind = "def" if d.kind == "function" else "class"
+        results.append((d.lineno, kind, src_line(d.lineno)))
     results.sort(key=lambda x: x[0])
     return results
 

py_cq/parsers/pytestparser.py

@@ -163,7 +163,7 @@ class PytestParser(AbstractParser):
         if "no tests ran" in raw_result.stdout:
             tr.metrics["tests"] = 0.0
         else:
-            tests_found = dict()
+            tests_found = {}
             num_tests = 0
             passed_tests = 0
             for line in lines:

py_cq/parsers/ruffparser.py

@@ -123,7 +123,7 @@ def _format_F821(file: str, line: int, message: str) -> str:
         base += f"\n\nOther references to `{name}` in this file:\n{ref_lines}"
     else:
         base += f"\n\n`{name}` is not imported or defined anywhere else in this file."
-    if enclosing:
+    if enclosing and enclosing not in base:
         base += f"\n\nEnclosing function:{enclosing}"
     return base
 

py_cq/source_file.py

@@ -0,0 +1,199 @@
+"""Process-scoped cache of parsed source files, shared across one ``cq check``.
+
+Within a single run the same ``.py`` file is otherwise read and parsed several
+times: by the normalized context hash, the coverage parser, the interrogate
+parser, and the LLM formatters. :class:`SourceFile` parses each file at most
+once and exposes lazy projections (functions, classes, docstring presence) that
+downstream consumers walk instead of re-parsing.
+
+The cache is keyed on ``(path, size, mtime)`` so a content change (which bumps
+``mtime``) misses and forces a fresh parse; correctness never depends on a hit.
+"""
+
+import ast
+import hashlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class FuncInfo:
+    """A function or class definition discovered in a source file.
+
+    ``signature`` is the rendered ``def`` line for functions and ``""`` for
+    classes (no consumer needs a class signature). ``kind`` is ``"function"``
+    or ``"class"``.
+    """
+
+    name: str
+    kind: str
+    lineno: int
+    end_lineno: int
+    has_docstring: bool
+    signature: str
+
+
+def _docstring_invariant_digest(tree: ast.AST) -> str:
+    """Return an md5 of ``tree`` with docstrings removed, leaving ``tree`` intact.
+
+    Docstring statements are temporarily detached, the tree is dumped and
+    hashed, then they are reattached - so the digest is docstring-invariant
+    without parsing a second time or mutating the tree that other consumers
+    share. Safe because the hash pass runs single-threaded before the tool pool.
+    """
+    detached = []
+    for node in ast.walk(tree):
+        if isinstance(
+            node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+        ):
+            body = node.body
+            if (
+                body
+                and isinstance(body[0], ast.Expr)
+                and isinstance(body[0].value, ast.Constant)
+                and isinstance(body[0].value.value, str)
+            ):
+                detached.append((node, body[0]))
+                node.body = body[1:]
+    digest = hashlib.md5(ast.dump(tree).encode()).hexdigest()  # nosec
+    for node, doc in detached:
+        node.body = [doc, *node.body]
+    return digest
+
+
+def _signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    """Return the signature of the function definition as a string."""
+    prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+    args = ast.unparse(node.args)
+    returns = f" -> {ast.unparse(node.returns)}" if node.returns else ""
+    return f"{prefix} {node.name}({args}){returns}"
+
+
+class SourceFile:
+    """Lazily-realized view of one source file: text, AST, and projections.
+
+    Fields are computed on first access and cached. ``.tree`` stays pristine
+    (docstrings intact) so multiple consumers can share it; ``.norm_digest``
+    derives its docstring-stripped digest from a throwaway reparse rather than
+    mutating ``.tree``.
+    """
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self._raw: bytes | None = None
+        self._text: str | None = None
+        self._tree: ast.AST | None = None
+        self._parsed = False
+        self._norm_digest: str | None = None
+        self._definitions: list[FuncInfo] | None = None
+
+    def _read_bytes(self) -> bytes:
+        if self._raw is None:
+            self._raw = Path(self.path).read_bytes()
+        return self._raw
+
+    @property
+    def text(self) -> str:
+        """Return the file contents decoded as UTF-8 (undecodable bytes replaced)."""
+        if self._text is None:
+            self._text = self._read_bytes().decode("utf-8", "replace")
+        return self._text
+
+    @property
+    def tree(self) -> ast.AST | None:
+        """Return the parsed AST, or ``None`` if the file can't be parsed."""
+        if not self._parsed:
+            self._parsed = True
+            try:
+                self._tree = ast.parse(self.text)
+            except (SyntaxError, ValueError):
+                self._tree = None
+        return self._tree
+
+    @property
+    def norm_digest(self) -> str:
+        """Return a docstring/comment/format-invariant digest of the file.
+
+        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 digest.
+        """
+        if self._norm_digest is None:
+            tree = self.tree
+            if tree is None:
+                self._norm_digest = hashlib.md5(self._read_bytes()).hexdigest()  # nosec
+            else:
+                self._norm_digest = _docstring_invariant_digest(tree)
+        return self._norm_digest
+
+    @property
+    def definitions(self) -> list[FuncInfo]:
+        """Return every function and class definition, in source order."""
+        if self._definitions is None:
+            defs: list[FuncInfo] = []
+            tree = self.tree
+            if tree is not None:
+                for node in ast.walk(tree):
+                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        defs.append(
+                            FuncInfo(
+                                node.name,
+                                "function",
+                                node.lineno,
+                                getattr(node, "end_lineno", node.lineno),
+                                ast.get_docstring(node) is not None,
+                                _signature(node),
+                            )
+                        )
+                    elif isinstance(node, ast.ClassDef):
+                        defs.append(
+                            FuncInfo(
+                                node.name,
+                                "class",
+                                node.lineno,
+                                getattr(node, "end_lineno", node.lineno),
+                                ast.get_docstring(node) is not None,
+                                "",
+                            )
+                        )
+                defs.sort(key=lambda d: d.lineno)
+            self._definitions = defs
+        return self._definitions
+
+    @property
+    def functions(self) -> list[FuncInfo]:
+        """Return the function definitions only (no classes), in source order."""
+        return [d for d in self.definitions if d.kind == "function"]
+
+    @property
+    def module_has_docstring(self) -> bool:
+        """Return True if the module has a docstring."""
+        tree = self.tree
+        return isinstance(tree, ast.Module) and ast.get_docstring(tree) is not None
+
+
+# Process-scoped memo: (path, size, mtime) -> SourceFile. A stale mtime only
+# forces a re-parse that reproduces the same projections, so correctness never
+# depends on this cache (matches the lock-free design: a duplicate parse is
+# harmless and GIL-serialized).
+_source_cache: dict[tuple[str, int, float], SourceFile] = {}
+
+
+def get_source(path: str) -> SourceFile:
+    """Return the cached :class:`SourceFile` for ``path``, creating it on miss.
+
+    Keyed on ``(canonical_path, size, mtime)``; a content change misses and
+    re-parses. The path is canonicalized (absolute + OS case folding) so the
+    hash pass and the parsers - which spell the same file differently (relative
+    vs. resolved/posix) - share one cache entry.
+
+    Raises:
+        OSError: If ``path`` cannot be stat'd.
+    """
+    s = os.stat(path)
+    key = (os.path.normcase(os.path.abspath(path)), s.st_size, s.st_mtime)
+    sf = _source_cache.get(key)
+    if sf is None:
+        sf = SourceFile(path)
+        _source_cache[key] = sf
+    return sf

py_cq/table_formatter.py

@@ -21,7 +21,7 @@ def format_as_table(
     table.add_column("Status")
     for tr in data.tool_results:
         tool_name = tr.raw.tool_name
-        config = next((t for t in registry.values() if t.name == tool_name))
+        config = next(t for t in registry.values() if t.name == tool_name)
         for i, (name, value) in enumerate(tr.metrics.items()):
             if value < config.error_threshold:
                 status = "[bold red]Error[/]"

py_cq/tool_registry.py

@@ -32,6 +32,9 @@ def load_tool_configs() -> dict[str, ToolConfig]:
             exclude_format=tool_data.get("exclude_format", ""),
             scan_exclude_names=tool_data.get("scan_exclude_names", []),
             skip_for_file=tool_data.get("skip_for_file", False),
+            gate_strict=tool_data.get("gate_strict", True),
+            skip_if=tool_data.get("skip_if", ""),
+            cache_invariant=tool_data.get("cache_invariant", ""),
         )
     return registry