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

py_cq/parsers/ruffparser.py

@@ -11,11 +11,149 @@ The concise output format is one violation per line::
 followed by a summary line ``Found N error.`` or ``All checks passed!``."""
 
 import re
+from collections.abc import Callable
+from pathlib import Path
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import format_source_context, score_logistic_variant
+from py_cq.parsers.common import (
+    enclosing_function_range,
+    extract_first_issue,
+    find_enclosing_function,
+    format_issue_header,
+    format_source_context,
+    score_logistic_variant,
+)
 
-_DIAG_RE = re.compile(r"^(.+):(\d+):(\d+): ([A-Z]\d+) (.+)$")
+_DIAG_RE = re.compile(r"^(.+):(\d+):(\d+): ([A-Z]{1,5}\d+) (.+)$")
+_VARNAME_RE = re.compile(r"[`'](\w+)[`']")
+
+
+def _format_F841(file: str, line: int, message: str) -> str:
+    """Unused variable: show source context, then report same-function references or advise deletion."""
+    base = format_issue_header(file, line, "F841", message) + format_source_context(
+        file, line
+    )
+    m = _VARNAME_RE.search(message)
+    if not m:
+        return base
+    var = m.group(1)
+    try:
+        lines = Path(file).read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return base
+    func_range = enclosing_function_range(file, line)
+    var_re = re.compile(rf"\b{re.escape(var)}\b")
+    refs = [
+        i + 1
+        for i, ln in enumerate(lines)
+        if i + 1 != line
+        and var_re.search(ln)
+        and (func_range is None or func_range[0] <= i + 1 <= func_range[1])
+    ]
+    if refs and len(var) > 1:
+        ref_str = ", ".join(str(r) for r in refs[:8])
+        return (
+            base
+            + f"\n\n`{var}` is also referenced at line(s): {ref_str}. Determine whether this assignment should feed into those uses or is redundant."
+        )
+    return (
+        base
+        + f"\n\n`{var}` is not referenced anywhere else in this function. Delete line {line}."
+    )
+
+
+def _format_F541(file: str, line: int, message: str) -> str:
+    """Format F541 error message."""
+    base = format_issue_header(file, line, "F541", message) + format_source_context(
+        file, line
+    )
+    return base + "\n\nFix: remove the `f` prefix from this string literal."
+
+
+def _file_refs(file: str, name: str, exclude_line: int) -> list[tuple[int, str]]:
+    """Return (line_no, stripped_text) for every line in file containing `name` as a word."""
+    try:
+        lines = Path(file).read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return []
+    name_re = re.compile(rf"\b{re.escape(name)}\b")
+    return [
+        (i + 1, ln.strip())
+        for i, ln in enumerate(lines)
+        if i + 1 != exclude_line and name_re.search(ln)
+    ]
+
+
+def _format_F401(file: str, line: int, message: str) -> str:
+    """Unused import: warn if name appears elsewhere (string annotations, __all__), else confirm safe delete."""
+    autofixable = "[*]" in message
+    clean_message = re.sub(r"^\[\*\]\s*", "", message)
+    base = format_issue_header(
+        file, line, "F401", clean_message
+    ) + format_source_context(file, line)
+    m = re.search(r"`([^`]+)`", clean_message)
+    if not m:
+        return base
+    # "typing.Optional" -> bound name is "Optional"; "os" -> "os"
+    name = m.group(1).split(".")[-1]
+    refs = _file_refs(file, name, exclude_line=line)
+    if refs:
+        ref_lines = "\n".join(f"  line {line_no}: {txt}" for line_no, txt in refs[:6])
+        return (
+            base
+            + f"\n\n`{name}` appears elsewhere in this file - verify these are not active uses before deleting:\n{ref_lines}"
+        )
+    suffix = " Auto-fixable: `ruff check --fix`." if autofixable else ""
+    return base + f"\n\nNo other uses found. Delete this import.{suffix}"
+
+
+def _format_F821(file: str, line: int, message: str) -> str:
+    """Undefined name: show enclosing function and all in-file references to help diagnose the gap."""
+    base = format_issue_header(file, line, "F821", message) + format_source_context(
+        file, line
+    )
+    m = re.search(r"`(\w+)`", message)
+    if not m:
+        return base
+    name = m.group(1)
+    refs = _file_refs(file, name, exclude_line=line)
+    enclosing = find_enclosing_function(file, line)
+    if refs:
+        ref_lines = "\n".join(f"  line {line_no}: {txt}" for line_no, txt in refs[:8])
+        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:
+        base += f"\n\nEnclosing function:{enclosing}"
+    return base
+
+
+def _format_E701(file: str, line: int, message: str) -> str:
+    base = format_issue_header(file, line, "E701", message) + format_source_context(
+        file, line, context=2, count=4
+    )
+    return base + "\n\nFix: split the second statement onto its own line."
+
+
+def _format_E721(file: str, line: int, message: str) -> str:
+    base = format_issue_header(file, line, "E721", message) + format_source_context(
+        file, line, context=2, count=4
+    )
+    return base + (
+        "\n\nFix: if comparing a type-holding variable against a type literal, use `is` "
+        "(e.g. `output_type is str`). If checking the type of a value, use `isinstance()` "
+        "(e.g. `isinstance(x, str)`)."
+    )
+
+
+_CUSTOM_FORMAT: dict[str, Callable[[str, int, str], str]] = {
+    "E701": _format_E701,
+    "E721": _format_E721,
+    "F401": _format_F401,
+    "F541": _format_F541,
+    "F821": _format_F821,
+    "F841": _format_F841,
+}
 
 
 class RuffParser(AbstractParser):
@@ -35,27 +173,33 @@ class RuffParser(AbstractParser):
             m = _DIAG_RE.match(line)
             if m:
                 path = m.group(1).replace("\\", "/")
-                files.setdefault(path, []).append({
-                    "line": int(m.group(2)),
-                    "code": m.group(4),
-                    "message": m.group(5),
-                })
+                files.setdefault(path, []).append(
+                    {
+                        "line": int(m.group(2)),
+                        "col": int(m.group(3)),
+                        "code": m.group(4),
+                        "message": m.group(5),
+                    }
+                )
         score = score_logistic_variant(
             sum(len(v) for v in files.values()), scale_factor=20
         )
         return ToolResult(raw=raw_result, metrics={"lint": score}, details=files)
 
-    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 the first lint violation as a defect description."""
-        if not tr.details:
-            return "ruff reported issues (no details available)"
-        file, issues = next(iter(tr.details.items()))
-        if not isinstance(issues, list) or not issues:
-            return "ruff reported issues (no details available)"
-        issue = issues[0]
-        if not isinstance(issue, dict):
+        result = extract_first_issue(tr.details)
+        if result is None:
             return "ruff reported issues (no details available)"
+        file, issue = result
         line = issue.get("line", "?")
         code = issue.get("code", "")
         message = issue.get("message", "")
-        return f"`{file}:{line}` — **{code}**: {message}{format_source_context(file, line, count=context_lines)}"
+        fmt_fn = _CUSTOM_FORMAT.get(code)
+        if fmt_fn and isinstance(line, int):
+            return fmt_fn(file, line, message)
+        return format_issue_header(file, line, code, message) + format_source_context(
+            file, line, count=context_lines
+        )

py_cq/parsers/typarser.py

@@ -12,72 +12,204 @@ followed by a summary line ``Found N diagnostic`` or ``All checks passed!``.
 Errors count more heavily than warnings toward the score."""
 
 import re
+from collections.abc import Callable
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import format_source_context, score_logistic_variant
+from py_cq.parsers.common import (
+    extract_first_issue,
+    find_enclosing_function,
+    format_issue_header,
+    format_source_context,
+    resolve_path,
+    score_logistic_variant,
+)
 
 _DIAG_RE = re.compile(r"^(.+):(\d+):\d+:\s+(error|warning)\[([^\]]+)\] (.+)$")
+_EXPECTED_FOUND_RE = re.compile(r"Expected `([^`]+)`, found `([^`]+)`")
 
-_CALL_CODES = frozenset([
-    "call-non-callable",
-    "missing-argument",
-    "unexpected-keyword",
-    "argument-type",
-    "too-many-positional-arguments",
-    "invalid-argument-type",
-    "no-matching-overload",
-])
+
+def _format_invalid_argument_type(file: str, line: int, message: str) -> str:
+    """Format a ty 'invalid-argument-type' diagnostic for LLM consumption.
+
+    Includes hint text when ty reports ``Unknown`` as the found type.
+
+    Args:
+        file: Resolved file path.
+        line: Line number of the diagnostic.
+        message: The diagnostic message from ty.
+
+    Returns:
+        Markdown-formatted issue report with fix hints.
+    """
+    display_msg = re.sub(r": (Expected `)", r":\n\1", message)
+    base = format_issue_header(
+        file, line, "invalid-argument-type", display_msg
+    ) + format_source_context(file, line)
+    m = _EXPECTED_FOUND_RE.search(message)
+    if not m or "Unknown" not in m.group(2):
+        return base
+    enclosing = find_enclosing_function(file, line)
+    note = "\n\n`Unknown` means ty cannot infer this argument's type - the variable has no annotation."
+    if enclosing:
+        note += (
+            f" Trace the argument back to its source and annotate its type:{enclosing}"
+        )
+    else:
+        note += " Annotate the variable's type or cast the argument explicitly."
+    return base + note
+
+
+_TYPE_NAME_RE = re.compile(r"Object of type `([^`]+)` is not callable")
+_MODULE_RE = re.compile(r"Submodule `([^`]+)`")
+_IMPORT_MODULE_RE = re.compile(r"Cannot resolve imported module `([^`]+)`")
+
+
+def _format_call_non_callable(file: str, line: int, message: str) -> str:
+    """Format a ty 'call-non-callable' diagnostic for LLM consumption.
+
+    Provides fix advice about incomplete type stubs and Callable annotations.
+
+    Args:
+        file: Resolved file path.
+        line: Line number of the diagnostic.
+        message: The diagnostic message from ty.
+
+    Returns:
+        Markdown-formatted issue report with fix hints.
+    """
+    base = format_issue_header(
+        file, line, "call-non-callable", message
+    ) + format_source_context(file, line, context=3, count=8)
+    m = _TYPE_NAME_RE.search(message)
+    type_name = f"`{m.group(1)}`" if m else "this type"
+    return base + (
+        f"\n\nty cannot see a `__call__` declaration on {type_name} - common when a library's "
+        f"type stubs are incomplete. Fix: annotate the variable as `Callable[..., <ReturnType>]`, "
+        f"or suppress with `# type: ignore[call-non-callable]` if the call is correct at runtime."
+    )
+
+
+def _format_possibly_missing_submodule(file: str, line: int, message: str) -> str:
+    """Format a ty 'possibly-missing-submodule' diagnostic for LLM consumption.
+
+    Advises adding an explicit import for the submodule before attribute access.
+
+    Args:
+        file: Resolved file path.
+        line: Line number of the diagnostic.
+        message: The diagnostic message from ty.
+
+    Returns:
+        Markdown-formatted issue report with fix hints.
+    """
+    base = format_issue_header(
+        file, line, "possibly-missing-submodule", message
+    ) + format_source_context(file, line, context=1, count=3)
+    m = _MODULE_RE.search(message)
+    submodule = m.group(1) if m else "the submodule"
+    return (
+        base
+        + f"\n\nFix: add `import <package>.{submodule}` before accessing it as an attribute."
+    )
+
+
+def _format_unresolved_import(file: str, line: int, message: str) -> str:
+    """Format a ty 'unresolved-import' diagnostic for LLM consumption.
+
+    Advises checking whether the module was renamed, deleted, or needs installation.
+
+    Args:
+        file: Resolved file path.
+        line: Line number of the diagnostic.
+        message: The diagnostic message from ty.
+
+    Returns:
+        Markdown-formatted issue report with fix hints.
+    """
+    base = format_issue_header(
+        file, line, "unresolved-import", message
+    ) + format_source_context(file, line, context=1, count=3)
+    m = _IMPORT_MODULE_RE.search(message)
+    module = f"`{m.group(1)}`" if m else "the module"
+    return base + (
+        f"\n\n{module} cannot be found. Check whether it has been renamed or deleted. "
+        f"If it is no longer needed, remove the import. "
+        f"If the module exists but is not installed, add it to your dependencies."
+    )
+
+
+_CUSTOM_FORMAT: dict[str, Callable[[str, int, str], str]] = {
+    "call-non-callable": _format_call_non_callable,
+    "invalid-argument-type": _format_invalid_argument_type,
+    "possibly-missing-submodule": _format_possibly_missing_submodule,
+    "unresolved-import": _format_unresolved_import,
+}
 
 
 class TyParser(AbstractParser):
     """Parses raw output from ``ty check`` into a structured ToolResult."""
 
     def parse(self, raw_result: RawResult) -> ToolResult:
-        """Parse concise ty output and return a ToolResult.
-
-        Args:
-            raw_result: Raw output from ``ty check --output-format concise``.
-
-        Returns:
-            ToolResult with a ``type_check`` metric in [0, 1] and per-file diagnostics in details.
-        """
         files: dict[str, list] = {}
+        seen: set[tuple[str, int, str]] = set()
         weighted = 0
         for line in (raw_result.stdout or "").splitlines():
             m = _DIAG_RE.match(line)
             if m:
                 path = m.group(1).replace("\\", "/")
+                lineno = int(m.group(2))
+                code = m.group(4)
                 severity = m.group(3)
-                files.setdefault(path, []).append({
-                    "line": int(m.group(2)),
-                    "code": m.group(4),
-                    "severity": severity,
-                    "message": m.group(5),
-                })
+                key = (path, lineno, code)
+                if key in seen:
+                    continue
+                seen.add(key)
+                files.setdefault(path, []).append(
+                    {
+                        "line": lineno,
+                        "code": code,
+                        "severity": severity,
+                        "message": m.group(5),
+                    }
+                )
                 weighted += 3 if severity == "error" else 1
 
         score = score_logistic_variant(weighted, scale_factor=10)
-        return ToolResult(raw=raw_result, metrics={"type_check": score}, details=files)
+        return ToolResult(
+            raw=raw_result,
+            metrics={"type_check": score},
+            details=files,
+            project_path=raw_result.project_path,
+        )
 
-    def format_llm_message(self, tr: ToolResult, *, context_lines: int = 15) -> str:
-        """Return the first type-check diagnostic as a defect description."""
-        if not tr.details:
-            return "ty reported issues (no details available)"
-        file, issues = next(iter(tr.details.items()))
-        if not isinstance(issues, list) or not issues:
-            return "ty reported issues (no details available)"
-        issue = issues[0]
-        if not isinstance(issue, dict):
+    def format_llm_message(
+        self, tr: ToolResult, *, context_lines: int = 15, limit: int = 1
+    ) -> str:
+        """Return a markdown description of the most important ty defect.
+
+        Delegates to a custom formatter when the code has a registered handler
+        in ``_CUSTOM_FORMAT`` (e.g. ``call-non-callable``, ``invalid-argument-type``),
+        otherwise falls back to the standard header + source context format.
+
+        Args:
+            tr: The parsed tool result containing details and raw output.
+            context_lines: Number of source context lines to show.
+            limit: Maximum number of issues to display (unused - always 1).
+
+        Returns:
+            Markdown-formatted issue description.
+        """
+        result = extract_first_issue(tr.details)
+        if result is None:
             return "ty reported issues (no details available)"
+        file, issue = result
         line = issue.get("line", "?")
         code = issue.get("code", "")
         message = issue.get("message", "")
-        src_ctx = format_source_context(file, line, count=context_lines)
-        callee = ""
-        if code in _CALL_CODES and isinstance(line, int):
-            from py_cq.parsers.common import extract_callee_name, format_callee_context, read_source_lines
-            src_line = read_source_lines(file, line, count=1)
-            func_name = extract_callee_name(src_line)
-            if func_name:
-                callee = format_callee_context(func_name, file)
-        return f"`{file}:{line}` — **{code}**: {message}{src_ctx}{callee}"
+        resolved_file = resolve_path(tr.project_path, file)
+        fmt_fn = _CUSTOM_FORMAT.get(code)
+        if fmt_fn and isinstance(line, int):
+            return fmt_fn(resolved_file, line, message)
+        return format_issue_header(
+            resolved_file, line, code, message
+        ) + format_source_context(resolved_file, line, count=context_lines)

py_cq/parsers/vultureparser.py

@@ -12,7 +12,11 @@ score stored under the ``dead_code`` metric key.
 import re
 
 from py_cq.localtypes import AbstractParser, RawResult, ToolResult
-from py_cq.parsers.common import format_source_context, score_logistic_variant
+from py_cq.parsers.common import (
+    extract_first_issue,
+    format_source_context,
+    score_logistic_variant,
+)
 
 _LINE_RE = re.compile(r"^(.+):(\d+): (unused \S+) '(.+)' \((\d+)% confidence\)$")
 
@@ -21,32 +25,34 @@ class VultureParser(AbstractParser):
     """Parses raw text output from ``vulture`` into a ToolResult."""
 
     def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parses the raw text output from vulture."""
         files: dict[str, list] = {}
         for line in (raw_result.stdout or "").splitlines():
             m = _LINE_RE.match(line)
             if m:
                 path = m.group(1).replace("\\", "/")
-                files.setdefault(path, []).append({
-                    "line": int(m.group(2)),
-                    "type": m.group(3),
-                    "name": m.group(4),
-                    "confidence": int(m.group(5)),
-                })
+                files.setdefault(path, []).append(
+                    {
+                        "line": int(m.group(2)),
+                        "type": m.group(3),
+                        "name": m.group(4),
+                        "confidence": int(m.group(5)),
+                    }
+                )
         count = sum(len(v) for v in files.values())
         score = score_logistic_variant(count, scale_factor=15)
         return ToolResult(raw=raw_result, metrics={"dead_code": score}, details=files)
 
-    def format_llm_message(self, tr: ToolResult, *, context_lines: int = 15) -> str:
-        if not tr.details:
-            return "vulture reported issues (no details available)"
-        file, issues = next(iter(tr.details.items()))
-        if not isinstance(issues, list) or not issues:
-            return "vulture reported issues (no details available)"
-        issue = issues[0]
-        if not isinstance(issue, dict):
+    def format_llm_message(
+        self, tr: ToolResult, *, context_lines: int = 15, limit: int = 1
+    ) -> str:
+        """Formats the LLM message from the ToolResult."""
+        result = extract_first_issue(tr.details)
+        if result is None:
             return "vulture reported issues (no details available)"
+        file, issue = result
         line = issue.get("line", "?")
         kind = issue.get("type", "unused")
         name = issue.get("name", "")
         confidence = issue.get("confidence", "?")
-        return f"`{file}:{line}` — **{kind}** `{name}` ({confidence}% confidence){format_source_context(file, line, count=context_lines)}"
+        return f"{file}:{line} - **{kind}** `{name}` ({confidence}% confidence){format_source_context(file, line, count=context_lines)}"

py_cq/table_formatter.py

@@ -1,11 +1,17 @@
 """Rich table formatter for combined tool results."""
 
 from rich.table import Table
+from rich.text import Text
 
 from py_cq.localtypes import CombinedToolResults, ToolConfig
 
 
-def format_as_table(data: CombinedToolResults, registry: dict[str, ToolConfig]) -> Table:
+def format_as_table(
+    data: CombinedToolResults,
+    registry: dict[str, ToolConfig],
+    *,
+    total_s: float | None = None,
+) -> Table:
     """Format combined tool results into a Rich Table."""
     table = Table(width=80)
     table.add_column("Tool", justify="left", no_wrap=True)
@@ -25,5 +31,13 @@ def format_as_table(data: CombinedToolResults, registry: dict[str, ToolConfig])
                 status = "[green]OK[/]"
             time_str = f"{tr.duration_s:.2f}s" if i == 0 else ""
             table.add_row(tool_name, time_str, name, f"{value:0.3f}", status)
-    table.add_row("", "", "[bold]Score[/]", f"[bold]{data.score:0.3f}[/]", "")
+    total_label = (
+        Text("Total", style="bold", justify="right")
+        if total_s is not None
+        else Text("")
+    )
+    total_time = f"[bold]{total_s:.2f}s[/]" if total_s is not None else ""
+    table.add_row(
+        total_label, total_time, "[bold]Score[/]", f"[bold]{data.score:0.3f}[/]", ""
+    )
     return table

py_cq/tool_registry.py

@@ -1,20 +1,19 @@
-"""Loads tool configurations from a YAML file and builds a registry that maps tool names to their configuration objects, enabling efficient lookup and instantiation of tools throughout the application. The module relies on PyYAML for parsing the configuration file."""
+"""Loads tool configurations from a TOML file and builds a registry that maps tool names to their configuration objects, enabling efficient lookup and instantiation of tools throughout the application."""
 
+import tomllib
 from importlib import import_module
 from importlib.resources import files
 
-import yaml
-
 from py_cq.localtypes import ToolConfig
 
 
 def load_tool_configs() -> dict[str, ToolConfig]:
-    """Load tool configurations from the bundled config.yaml and return a registry.
+    """Load tool configurations from the bundled config.toml and return a registry.
 
     Returns:
         dict[str, ToolConfig]: A mapping from tool ID to its configuration instance."""
-    yaml_text = files("py_cq.config").joinpath("config.yaml").read_text(encoding="utf-8")
-    config = yaml.safe_load(yaml_text)
+    toml_bytes = files("py_cq.config").joinpath("config.toml").read_bytes()
+    config = tomllib.loads(toml_bytes.decode())
     registry = {}
     for tool_id, tool_data in config["python"].items():
         # Dynamically import parser class
@@ -31,6 +30,8 @@ def load_tool_configs() -> dict[str, ToolConfig]:
             extra_deps=tool_data.get("extra_deps", []),
             parser_config=tool_data.get("parser_config", {}),
             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),
         )
     return registry