python-code-quality 0.1.4__py3-none-any.whl

py_cq/__init__.py

@@ -0,0 +1,10 @@
+"""Provides a simple greeting function that returns a friendly message.
+
+The module defines a single function, `hello`, which returns the string
+`'Hello from py_cq!'`. It can serve as a minimal example, placeholder, or
+testing stub in larger applications."""
+
+
+def hello() -> str:
+    """Returns the greeting string `'Hello from py_cq!'`."""
+    return "Hello from py_cq!"

py_cq/cli.py

@@ -0,0 +1,229 @@
+"""CLI for static analysis of Python projects.
+
+Provides a Typer command `check` that accepts a path to a Python file or project
+directory, executes a suite of static analysis tools, aggregates their
+results, and outputs the data either as JSON or as a human-readable Rich
+table.  The command supports configurable logging, cache clearing,
+score-only output, and optional parallel execution to accelerate
+analysis.
+
+Helper functions such as `format_as_table` convert the aggregated tool
+results into a Rich Table for convenient console display.
+"""
+
+import copy
+import json
+import logging
+import tomllib
+from enum import Enum
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.table import Table
+
+from py_cq.config import DEFAULT_STORAGE_FILE, load_user_config
+from py_cq.execution_engine import _cache as tool_cache
+from py_cq.execution_engine import run_tools
+from py_cq.localtypes import CombinedToolResults, ToolConfig
+from py_cq.metric_aggregator import aggregate_metrics
+from py_cq.storage import save_result
+from py_cq.tool_registry import tool_registry
+
+logging.basicConfig(
+    level="INFO",
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(markup=True)],
+)
+log = logging.getLogger("cq")
+app = typer.Typer(
+    epilog=(
+        "Examples:\n\n"
+        "  cq check .          # full table with all metrics (default)\n\n"
+        "  cq check . -o llm   # top defect as markdown (primary LLM workflow)\n\n"
+        "  cq check . -o score # numeric score only\n\n"
+        "  cq config .         # show effective tool configuration"
+    ),
+)
+
+
+def _apply_user_config(base: dict[str, ToolConfig], user_cfg: dict) -> dict[str, ToolConfig]:
+    """Return a modified copy of base with user overrides applied.
+
+    Supports:
+      - ``disable``: list of tool IDs to remove
+      - ``thresholds.<tool_id>.warning`` / ``.error``: override per-tool thresholds
+    """
+    registry = {k: copy.copy(v) for k, v in base.items()}
+    for tool_id in user_cfg.get("disable", []):
+        registry.pop(tool_id, None)
+    for tool_id, thresholds in user_cfg.get("thresholds", {}).items():
+        if tool_id in registry:
+            if "warning" in thresholds:
+                registry[tool_id].warning_threshold = float(thresholds["warning"])
+            if "error" in thresholds:
+                registry[tool_id].error_threshold = float(thresholds["error"])
+    return registry
+
+
+class OutputMode(str, Enum):
+    """Enum of output types."""
+    TABLE = "table"
+    SCORE = "score"
+    JSON = "json"
+    LLM = "llm"
+
+
+@app.callback()
+def callback():
+    """CQ - Code Quality Analysis Tool."""
+console = Console()
+
+
+@app.command()
+def check(
+    path: str = typer.Argument(".", help="Path to Python file or project directory"),
+    output: OutputMode = typer.Option(
+        OutputMode.TABLE, "--output", "-o", help="Output mode: table (default), score, json, llm"
+    ),
+    log_level: str = typer.Option(
+        "CRITICAL",
+        "--log-level",
+        help="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
+    ),
+    out_file: str = typer.Option(
+        DEFAULT_STORAGE_FILE,
+        "--out-file",
+        help="File path to save results in table mode",
+    ),
+    clear_cache: bool = typer.Option(
+        False, "--clear-cache", help="Clear cached tool results before running"
+    ),
+    workers: int = typer.Option(
+        0, "--workers", help="Max parallel workers (default: one per tool, use 1 for sequential)"
+    ),
+):
+    """Run static analysis on a Python file or project directory."""
+    path_obj = Path(path)
+    if not path_obj.exists():
+        raise typer.BadParameter(f"Path does not exist: {path}")
+    if path_obj.is_file():
+        if path_obj.suffix != ".py":
+            raise typer.BadParameter(f"File must be a Python file (.py): {path}")
+    elif path_obj.is_dir():
+        if not (path_obj / "pyproject.toml").exists():
+            raise typer.BadParameter(f"Directory must contain pyproject.toml: {path}")
+    log.setLevel(log_level)
+    effective_registry = _apply_user_config(tool_registry, load_user_config(path_obj))
+    if clear_cache:
+        tool_cache.clear()
+    tool_results = run_tools(effective_registry.values(), path, workers)
+    for tr in tool_results:
+        log.debug(json.dumps(tr.to_dict(), indent=2))
+    combined_metrics = aggregate_metrics(path=path, metrics=tool_results)
+    if output == OutputMode.SCORE:
+        console.print(combined_metrics.score)
+    elif output == OutputMode.JSON:
+        console.print(json.dumps(combined_metrics.to_dict(), indent=2))
+    elif output == OutputMode.LLM:
+        log.setLevel("CRITICAL")
+        from py_cq.llm_formatter import format_for_llm
+        console.print(format_for_llm(effective_registry, combined_metrics))
+    else:
+        save_result(combined_tool_results=combined_metrics, file_name=out_file)
+        console.print(format_as_table(combined_metrics, effective_registry))
+
+
+@app.command()
+def config(
+    path: str = typer.Argument(".", help="Path to Python file or project directory"),
+) -> None:
+    """Show the effective tool configuration for a project."""
+    path_obj = Path(path).resolve()
+    toml_path = (
+        path_obj.parent / "pyproject.toml"
+        if path_obj.is_file()
+        else path_obj / "pyproject.toml"
+    )
+
+    if not toml_path.exists():
+        status_text = "[yellow]file not found[/yellow]"
+        user_cfg: dict = {}
+    else:
+        with toml_path.open("rb") as f:
+            toml_data = tomllib.load(f)
+        cq_section = toml_data.get("tool", {}).get("cq")
+        if cq_section is None:
+            status_text = "[yellow]no [tool.cq] section[/yellow]"
+            user_cfg = {}
+        else:
+            status_text = "[green]merged from [tool.cq][/green]"
+            user_cfg = cq_section
+
+    console.print(f"Config: [bold]{toml_path}[/bold] ({status_text})\n")
+
+    effective_registry = _apply_user_config(tool_registry, user_cfg)
+    disabled_ids = set(tool_registry.keys()) - set(effective_registry.keys())
+
+    table = Table()
+    table.add_column("Tool", style="cyan")
+    table.add_column("Priority", justify="right")
+    table.add_column("Warning", justify="right")
+    table.add_column("Error", justify="right")
+    table.add_column("Status", justify="center")
+
+    for tool_id in sorted(tool_registry, key=lambda t: tool_registry[t].priority):
+        tc = effective_registry.get(tool_id, tool_registry[tool_id])
+        is_disabled = tool_id in disabled_ids
+        status = "[red]disabled[/red]" if is_disabled else "[green]enabled[/green]"
+        table.add_row(
+            tc.name,
+            str(tc.priority),
+            f"{tc.warning_threshold:.2f}",
+            f"{tc.error_threshold:.2f}",
+            status,
+        )
+
+    console.print(table)
+
+
+def format_as_table(data: CombinedToolResults, registry: dict[str, ToolConfig]):
+    """Format combined tool results into a Rich Table.
+
+    Args:
+        data (CombinedToolResults): Aggregated tool results, including the path,
+            individual tool results, and the overall score.
+
+    Returns:
+        rich.table.Table: A Rich table with columns ``Tool``, ``Metric``, ``Score`` and
+        ``Status``. Each metric row displays a status icon based on thresholds from
+        the tool's configuration. The table is titled with the data path and ends
+        with a row showing the overall score.
+
+    Example:
+        >>> table = format_as_table(combined_results)
+        >>> console.print(table)
+    """
+    table = Table(title=f"[bold green]{data.path}[/]", width=80)
+    table.add_column("Tool", justify="left", no_wrap=True)
+    table.add_column("Time", justify="right", style="dim")
+    table.add_column("Metric", justify="right", style="cyan", no_wrap=True)
+    table.add_column("Score", style="magenta")
+    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))
+        for i, (name, value) in enumerate(tr.metrics.items()):
+            status = ""
+            if value < config.error_threshold:
+                status = "[bold red]Error[/]"
+            elif value < config.warning_threshold:
+                status = "[yellow]Warning[/]"
+            else:
+                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}[/]", "")
+    return table

py_cq/config/__init__.py

@@ -0,0 +1,27 @@
+"""Default storage path and user config loader."""
+
+import tomllib
+from pathlib import Path
+
+DEFAULT_STORAGE_FILE = ".cq.json"
+
+
+def load_user_config(project_path: Path) -> dict:
+    """Read [tool.cq] from pyproject.toml at project_path, if present.
+
+    Args:
+        project_path: Path to the project directory or a .py file.
+
+    Returns:
+        The contents of [tool.cq] as a plain dict, or {} if absent.
+    """
+    toml_path = (
+        project_path.parent / "pyproject.toml"
+        if project_path.is_file()
+        else project_path / "pyproject.toml"
+    )
+    if not toml_path.exists():
+        return {}
+    with toml_path.open("rb") as f:
+        data = tomllib.load(f)
+    return data.get("tool", {}).get("cq", {})

py_cq/config/tools.yaml

@@ -0,0 +1,97 @@
+tools:
+
+  compilation:
+    name: "compile"
+    command: "{python} -m compileall -r 10 -j 8 {context_path} -x .*venv"
+    parser: "CompileParser"
+    priority: 1
+    warning_threshold: 0.9999
+    error_threshold: 0.9999
+
+  bandit:
+    name: "bandit"
+    command: "{python} -m bandit -r {context_path} -f json -q -s B101 --severity-level medium --exclude ./.venv,./tests/"
+    parser: "BanditParser"
+    priority: 2
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+
+  ruff:
+    name: "ruff"
+    command: "{python} -m ruff check --output-format concise --no-cache {context_path}"
+    parser: "RuffParser"
+    priority: 3
+    warning_threshold: 0.9999
+    error_threshold: 0.9
+
+  ty:
+    name: "ty"
+    command: "{python} -m ty check --output-format concise --color never {context_path}"
+    parser: "TyParser"
+    priority: 4
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+    run_in_target_env: true
+    extra_deps:
+      - ty
+
+  pytest:
+    name: "pytest"
+    command: "{python} -m pytest -v {context_path}"
+    parser: "PytestParser"
+    priority: 5
+    warning_threshold: 0.7
+    error_threshold: 0.5
+    run_in_target_env: true
+
+  coverage:
+    name: "coverage"
+    command: "{python} -m coverage run -m pytest {context_path} && {python} -m coverage report"
+    parser: "CoverageParser"
+    priority: 6
+    warning_threshold: 0.9
+    error_threshold: 0.5
+    run_in_target_env: true
+    extra_deps:
+      - coverage
+      - pytest
+
+  complexity:
+    name: "radon cc"
+    command: "{python} -m radon cc --json {context_path}"
+    parser: "ComplexityParser"
+    priority: 7
+    warning_threshold: 0.6
+    error_threshold: 0.4
+
+  maintainability:
+    name: "radon mi"
+    command: "{python} -m radon mi -s --json {context_path}"
+    parser: "MaintainabilityParser"
+    priority: 8
+    warning_threshold: 0.6
+    error_threshold: 0.4
+
+  halstead:
+    name: "radon hal"
+    command: "{python} -m radon hal -f --json {context_path}"
+    parser: "HalsteadParser"
+    priority: 9
+    warning_threshold: 0.5
+    error_threshold: 0.3
+
+  vulture:
+    name: "vulture"
+    command: "{python} -m vulture {context_path} --min-confidence 80 --exclude .venv,dist,.*_cache,docs,.git"
+    parser: "VultureParser"
+    priority: 10
+    warning_threshold: 0.9999
+    error_threshold: 0.8
+
+  interrogate:
+    name: "interrogate"
+    command: "{python} -m interrogate {context_path} -v --fail-under 0"
+    parser: "InterrogateParser"
+    priority: 11
+    warning_threshold: 0.8
+    error_threshold: 0.3

py_cq/context_hash.py

@@ -0,0 +1,81 @@
+"""Utilities for computing cryptographic signatures and context hashes.
+
+This module offers two lightweight helpers that simplify integrity checks and
+change-detection in larger systems:
+
+* **`get_sigs(path)`** - Recursively scans a directory tree and returns a list of
+  signature strings for all Python files, ignoring virtual-environment and
+  cache directories. Each signature encodes the file path, its size in bytes,
+  and its last-modified timestamp (`st_mtime`).
+
+* **`get_context_hash(path)`** - Computes an MD5 digest that uniquely identifies
+  a file or directory. For a file it hashes its path, size, and modification
+  time; for a directory it aggregates the signatures of all contained files.
+
+These functions provide deterministic fingerprints that can be used for
+file integrity verification, caching, and change-detection logic.
+"""
+
+import hashlib
+import os
+
+
+def get_sigs(path: str):
+    """Recursively scans a directory tree and returns a list of signatures for all Python files.
+
+    The signature format is ``<file_path>:<size_bytes>:<mtime>`` where ``mtime`` is the
+    last modification timestamp retrieved from ``os.stat``. The traversal skips
+    directories named ``.venv``, ``venv`` and ``__pycache__``.
+
+    Args:
+        path (str): The root directory to scan.
+
+    Returns:
+        list[str]: A signature string for each ``.py`` file found.
+
+    Raises:
+        FileNotFoundError: If ``path`` does not exist.
+        PermissionError: If the process cannot access a directory or file.
+
+    Example:
+        >>> get_sigs('/tmp/project')
+        ['/tmp/project/main.py:1024:1680000000.0', ...]
+    """
+    items = []
+    with os.scandir(path) as entries:
+        for entry in entries:
+            if entry.is_file() and entry.name.endswith(".py"):
+                stat_info = entry.stat()
+                items.append(f"{entry.path}:{stat_info.st_size}:{stat_info.st_mtime}")
+            if entry.is_dir() and entry.name not in [".venv", "venv", "__pycache__"]:
+                items.extend(get_sigs(entry.path))
+    return items
+
+
+def get_context_hash(path: str):
+    """Compute an MD5 hash that uniquely identifies a file or directory.
+
+    The hash is derived from a signature string. For a file, the signature consists of
+    its path, size, and modification time. For a directory, the signature is the
+    concatenation of the signatures of all files within it (recursively).
+
+    Args:
+        path (str): The filesystem path to hash.
+
+    Returns:
+        str: The hexadecimal MD5 digest.
+
+    Raises:
+        OSError: If the file or directory cannot be accessed.
+
+    Example:
+        >>> get_context_hash('/tmp/example.txt')
+        '5d41402abc4b2a76b9719d911017c592'
+    """
+    sig = "empty"
+    if os.path.isfile(path):
+        s = os.stat(path)
+        sig = f"{path}:{s.st_size}:{s.st_mtime}"
+    elif os.path.isdir(path):
+        sig = "".join(get_sigs(path=path))
+    return f"{hashlib.md5(sig.encode('utf-8')).hexdigest()}" # nosec

py_cq/execution_engine.py

@@ -0,0 +1,160 @@
+"""Utilities for executing tools and caching their results.
+
+This module provides helper functions to run command-line tools while
+automatically caching their output.  The key capabilities are:
+
+* ``run_tool`` - executes a single tool configuration, captures its
+  stdout/stderr/return code, and records a timestamp.
+* ``run_tools`` - runs many tool configurations, optionally in parallel,
+  and returns the parsed results.
+
+All functions are designed for reuse in data-processing pipelines
+where tool invocations may be expensive and should be avoided
+when a cached result already exists."""
+
+import logging
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Collection
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import cast
+
+import diskcache
+
+from py_cq.context_hash import get_context_hash
+from py_cq.localtypes import RawResult, ToolConfig, ToolResult
+
+log = logging.getLogger("cq")
+
+_cache = diskcache.Cache(Path.home() / ".cache" / "cq")
+
+
+def _find_project_root(path: Path) -> Path | None:
+    """Walk up from path to find the nearest directory containing pyproject.toml."""
+    for parent in [path] + list(path.parents):
+        candidate = parent if parent.is_dir() else parent.parent
+        if (candidate / "pyproject.toml").exists():
+            return candidate
+    return None
+
+
+def run_tool(tool_config: ToolConfig, context_path: str) -> RawResult:
+    """Runs a tool defined by its configuration and returns the execution result.
+
+    Args:
+        tool_config (ToolConfig): Configuration object containing the tool's name and a
+            command template.
+        context_path (str): Filesystem path that will be substituted into the command
+            template via ``context_path`` formatting.
+
+    Returns:
+        RawResult: An object holding the tool name, the command that was executed,
+            standard output, standard error, the process return code, and a timestamp
+            of when the command finished.
+
+    Example:
+        >>> result = run_tool(my_tool_config, "/tmp/context")
+        >>> result.return_code
+        0"""
+    python = sys.executable
+    path = context_path
+    if tool_config.run_in_target_env:
+        uv = shutil.which("uv")
+        if uv:
+            resolved = Path(context_path).resolve()
+            if resolved.is_dir():
+                abs_dir = str(resolved)
+                path = "."
+            else:
+                project_root = _find_project_root(resolved)
+                abs_dir = str(project_root) if project_root else str(resolved.parent)
+                path = str(resolved)
+            with_flags = " ".join(f"--with {dep}" for dep in tool_config.extra_deps)
+            python = f'"{uv}" run --directory "{abs_dir}" {with_flags}'.rstrip()
+    command = tool_config.command.format(context_path=path, python=python)
+    cache_key = f"{command}:{get_context_hash(context_path)}"
+    if cache_key in _cache:
+        log.info(f"Cache hit: {command}")
+        return cast(RawResult, _cache[cache_key])
+    log.info(f"Running: {command}")
+    result = subprocess.run(command, capture_output=True, text=True, shell=True) # nosec
+    timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
+    raw_result = RawResult(
+        tool_name=tool_config.name,
+        command=command,
+        stdout=result.stdout,
+        stderr=result.stderr,
+        return_code=result.returncode,
+        timestamp=timestamp,
+    )
+    _cache[cache_key] = raw_result
+    return raw_result
+
+
+def run_tools(tool_configs: Collection[ToolConfig], path: str, max_workers: int = 0) -> list[ToolResult]:
+    """Run multiple tools and return their parsed results.
+
+    Runs each tool specified in *tool_configs* on the file or directory at
+    *path*. Each tool is executed through :func:`run_tool`, and its output is
+    parsed by the tool's ``parser_class`` to produce a :class:`ToolResult`.
+    When *parallel* is ``True`` the tools are run concurrently with a
+    :class:`concurrent.futures.ThreadPoolExecutor` limited to at most four
+    workers. Exceptions raised by a tool during parallel execution are logged
+    via ``log.error``; in serial mode the exception propagates to the caller.
+
+    Args:
+        tool_configs (Iterable[ToolConfig]):
+            A sequence of tool configuration objects.  Each object must expose
+            a ``name`` attribute, a ``parser_class`` callable, and any other
+            information required by :func:`run_tool`.
+        path (str):
+            Path to the input file or directory that the tools should analyze.
+        parallel (bool, optional):
+            If ``True``, run the tools in parallel using a thread pool
+            (default: ``False``).
+
+    Returns:
+        list[ToolResult]:
+            A list containing the parsed results for each tool, in the same
+            order as *tool_configs*.
+
+    Raises:
+        RuntimeError:
+            If a non-parallel execution encounters an exception from
+            :func:`run_tool` or the parser.  In parallel mode exceptions are
+            logged instead of being raised.
+
+    Example:
+        >>> from mymodule import run_tools, ToolConfig
+        >>> configs = [
+        ...     ToolConfig(name='lint', parser_class=LintParser),
+        ...     ToolConfig(name='scan', parser_class=ScanParser),
+        ... ]
+        >>> results = run_tools(configs, '/path/to/project', parallel=True)"""
+    def _run_and_parse(tool_config: ToolConfig) -> tuple[int, ToolResult]:
+        t0 = time.perf_counter()
+        raw_result = run_tool(tool_config, path)
+        tr = tool_config.parser_class().parse(raw_result)
+        tr.duration_s = time.perf_counter() - t0
+        return tool_config.priority, tr
+
+    if not tool_configs:
+        return []
+    t_start = time.perf_counter()
+    prioritized: list[tuple[int, ToolResult]] = []
+    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
+        }
+        for future in as_completed(future_to_tool):
+            tool_config = future_to_tool[future]
+            try:
+                prioritized.append(future.result())
+            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")
+    return [tr for _, tr in sorted(prioritized)]

py_cq/llm_formatter.py

@@ -0,0 +1,47 @@
+"""Format the most important code quality defect as a markdown prompt for LLM consumption."""
+
+import sys
+
+from py_cq.localtypes import CombinedToolResults, ToolConfig
+
+
+def _severity(score: float, config: ToolConfig) -> int:
+    """Return 0 (error), 1 (warning), or 2 (ok) for a given score and tool config."""
+    if score < config.error_threshold:
+        return 0
+    if score < config.warning_threshold:
+        return 1
+    return 2
+
+
+def format_for_llm(
+    tool_configs: dict,
+    combined: CombinedToolResults,
+    cq_invocation: str | None = None,
+) -> str:
+    """Return a markdown prompt describing the single most important defect."""
+    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
+        ],
+        key=lambda tr: (
+            _severity(min(tr.metrics.values()), by_name[tr.raw.tool_name]),
+            by_name[tr.raw.tool_name].priority,
+            min(tr.metrics.values()),
+        ),
+    )
+    if not failing:
+        return f"# No issues found\n\nOverall score: **{combined.score:.3f} / 1.0**"
+
+    worst = failing[0]
+    config = by_name[worst.raw.tool_name]
+    defect_md = config.parser_class().format_llm_message(worst)
+    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."
+    )