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

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
 
 

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"}
 
@@ -31,12 +32,16 @@ def _format_missing_docstring(file_str: str, line: int, code: str, message: str)
     )
 
     if code == "D100":
-        return base + "\n\nInsert a module-level docstring as the very first statement in the file."
+        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):
@@ -72,6 +77,7 @@ def _format_missing_docstring(file_str: str, line: int, code: str, message: str)
 
     return base + "\n\nInsert a docstring as the first statement in the body."
 
+
 _ROW_RE = re.compile(
     r"^\|\s+(.+?)\s+\|\s+(\d+)\s+\|\s+(\d+)\s+\|\s+\d+\s+\|\s+(\d+(?:\.\d+)?)%\s*\|"
 )
@@ -83,12 +89,14 @@ def _load_interrogate_cfg(context_path: str) -> dict:
     """Read [tool.interrogate] from the nearest pyproject.toml."""
     p = Path(context_path).resolve()
     for candidate in [p, *p.parents]:
-        pyproject = (candidate if candidate.is_dir() else candidate.parent) / "pyproject.toml"
+        pyproject = (
+            candidate if candidate.is_dir() else candidate.parent
+        ) / "pyproject.toml"
         if pyproject.exists():
             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,12 +112,12 @@ 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]]:
+def _missing_docstrings(
+    file_path: Path, cfg: dict | None = None
+) -> list[tuple[int, str, str]]:
     """Return (line, kind, source_line) for each node missing a docstring.
 
     kind is 'module', 'def', or 'class'. source_line is the verbatim text of
@@ -117,11 +125,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 []
+    if tree is None:
         return []
-    src_lines = source.splitlines()
+    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 +147,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/ruffformatparser.py

@@ -0,0 +1,62 @@
+"""Parses output from ruff format --check into a standardized ToolResult.
+
+The output is one line per unformatted file. ruff >= 0.16 honours
+``--output-format concise``::
+
+    <file>:<line>:<col>: unformatted: File would be reformatted
+
+while older versions ignore it (it needs preview mode) and print::
+
+    Would reformat: <file>
+
+Either is followed by a summary line such as
+``2 files would be reformatted, 30 files already formatted`` or
+``32 files already formatted``.
+
+The score is the fraction of checked files that are already formatted,
+taken from the summary so it stays correct if the per-file format changes."""
+
+import re
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import extract_first_issue
+
+_FILE_RE = re.compile(r"^(?:Would reformat: (.+)|(.+):\d+:\d+: unformatted: .*)$")
+_FORMATTED_RE = re.compile(r"(\d+) files? already formatted")
+_UNFORMATTED_RE = re.compile(r"(\d+) files? would be reformatted")
+
+
+class RuffFormatParser(AbstractParser):
+    """Parses ``ruff format --check --output-format concise`` output into a ToolResult."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Collect unformatted files and score the fraction already formatted."""
+        stdout = raw_result.stdout or ""
+        # One issue per file, with no line: the line ruff reports is the first
+        # diff hunk, which would make the fingerprint unstable across edits.
+        files: dict[str, list] = {}
+        for line in stdout.splitlines():
+            m = _FILE_RE.match(line)
+            if m:
+                files[(m.group(1) or m.group(2)).replace("\\", "/")] = [{}]
+        m = _FORMATTED_RE.search(stdout)
+        formatted = int(m.group(1)) if m else 0
+        m = _UNFORMATTED_RE.search(stdout)
+        unformatted = max(int(m.group(1)) if m else 0, len(files))
+        total = formatted + unformatted
+        score = formatted / total if total else 1.0
+        return ToolResult(raw=raw_result, metrics={"formatted": score}, details=files)
+
+    def format_llm_message(
+        self, tr: ToolResult, *, context_lines: int = 15, limit: int = 1
+    ) -> str:
+        """Ask for the formatter to be run rather than a hand edit."""
+        result = extract_first_issue(tr.details)
+        if result is None:
+            return "ruff format reported issues (no details available)"
+        file, _ = result
+        return (
+            f"{file} - **not formatted**. Run the formatter, do not edit by hand:\n\n"
+            f"```bash\nruff format {file}\n```\n\n"
+            "Other files may also need formatting; `ruff format .` fixes them all."
+        )

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

@@ -34,6 +34,7 @@ def load_tool_configs() -> dict[str, ToolConfig]:
             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