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

py_cq/parsers/halsteadparser.py

@@ -0,0 +1,174 @@
+"""Utilities for parsing Halstead-based metrics.
+
+This module implements :class:`HalsteadParser`, an ``AbstractParser`` that
+converts the JSON output from Halstead metric tools into a
+``ToolResult``.  It extracts bug estimates and program volume, applies
+maximum thresholds, and aggregates file- and function-level metrics."""
+
+import json
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import score_logistic_variant
+
+
+class HalsteadParser(AbstractParser):
+    """Parses Halstead metric output and converts it into a `ToolResult`.
+
+    Implements the `AbstractParser` interface for tools that emit
+    Halstead-based JSON.  The `parse` method consumes a `RawResult`,
+    extracts per-file and per-function metrics, applies the configured
+    maximum bug and volume thresholds, and aggregates the results.
+    The helper `extract_bugs_and_volume` performs the core calculation of
+    bug-free and smallness scores.
+
+    The parser also records the tool's return code and any errors in the
+    result details."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parses Halstead tool JSON output and returns a ToolResult.
+
+        The method reads ``raw_result.stdout``—a JSON string containing
+        per-file and per-function Halstead metrics. For each file it
+        populates a ``ToolResult`` detail entry with bug-free and
+        smallness scores. If a file contains an ``error`` key, the
+        associated metrics are set to zero and the error message is
+        stored. File-level and function-level thresholds are applied
+        when computing metrics via :meth:`extract_bugs_and_volume`.
+
+        After processing all entries, aggregate metrics
+        (``file_bug_free``, ``file_smallness``,
+        ``functions_bug_free``, ``functions_smallness``) are calculated
+        from the minimum values observed. The tool's return code is also
+        recorded in the ``ToolResult`` details.
+
+        Args:
+            raw_result (RawResult): The raw output from a Halstead
+                analysis tool. Its ``stdout`` attribute must contain a
+                JSON string with the expected structure.
+
+        Returns:
+            ToolResult: A populated ``ToolResult`` instance with
+                detailed per-file and per-function metrics, aggregate
+                metrics, and the tool's return code.
+
+        Raises:
+            json.JSONDecodeError: If the ``stdout`` cannot be parsed as
+                JSON."""
+        # radon hal -f --json .\data\problems\travelling_salesman\ts_bad.py
+        # {".\\data\\problems\\travelling_salesman\\ts_bad.py":
+        #  {"total": {"h1": 6, "h2": 18, "N1": 13, "N2": 22, "vocabulary": 24, "length": 35, "calculated_length": 90.56842503028855, "volume": 160.4736875252405, "difficulty": 3.6666666666666665, "effort": 588.4035209258818, "time": 32.68908449588233, "bugs": 0.05349122917508017},
+        #   "functions": {"calc_dist": {"h1": 3, "h2": 9, "N1": 5, "N2": 10, "vocabulary": 12, "length": 15, "calculated_length": 33.28421251514428, "volume": 53.77443751081735, "difficulty": 1.6666666666666667, "effort": 89.62406251802892, "time": 4.9791145843349405, "bugs": 0.017924812503605784}, "find_nearest_city": {"h1": 1, "h2": 2, "N1": 1, "N2": 2, "vocabulary": 3, "length": 3, "calculated_length": 2.0, "volume": 4.754887502163469, "difficulty": 0.5, "effort": 2.3774437510817346, "time": 0.1320802083934297, "bugs": 0.0015849625007211565}, "generate_tour": {"h1": 2, "h2": 5, "N1": 6, "N2": 8, "vocabulary": 7, "length": 14, "calculated_length": 13.60964047443681, "volume": 39.302968908806456, "difficulty": 1.6, "effort": 62.884750254090335, "time": 3.493597236338352, "bugs": 0.01310098963626882}, "main": {"h1": 0, "h2": 0, "N1": 0, "N2": 0, "vocabulary": 0, "length": 0, "calculated_length": 0, "volume": 0, "difficulty": 0, "effort": 0, "time": 0.0, "bugs": 0.0}}}
+        tr = ToolResult(raw=raw_result)
+        MAX_FILE_BUGS = 1
+        MAX_FILE_VOLUME = 2000
+        MAX_FUNCTION_BUGS = 0.2
+        MAX_FUNCTION_VOLUME = 300
+        min_file_nb = 1.0
+        min_file_sm = 1.0
+        min_function_nb = 1.0
+        min_function_sm = 1.0
+        data = json.loads(raw_result.stdout)
+        for file, values in data.items():
+            file_name = file.replace("\\", "/")
+            if file_name not in tr.details:
+                tr.details[file_name] = {
+                    "bug_free": 0.0,
+                    "smallness": 0.0,
+                    "functions": {},
+                }
+            if "error" in values:
+                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"]
+            if "total" in values:
+                nb, sm = self.extract_bugs_and_volume(
+                    values.get("total", {}), MAX_FILE_BUGS, MAX_FILE_VOLUME
+                )
+                min_file_nb = min(nb, min_file_nb)
+                min_file_sm = min(sm, min_file_sm)
+                tr.details[file_name]["bug_free"] = nb
+                tr.details[file_name]["smallness"] = sm
+                tr.details[file_name]["bugs"] = values["total"].get("bugs", 0)
+                tr.details[file_name]["volume"] = values["total"].get("volume", 0)
+            if "functions" in values:
+                for function, function_values in values["functions"].items():
+                    nb, sm = self.extract_bugs_and_volume(
+                        function_values, MAX_FUNCTION_BUGS, MAX_FUNCTION_VOLUME
+                    )
+                    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,
+                        "smallness": sm,
+                        "bugs": function_values.get("bugs", 0),
+                        "volume": function_values.get("volume", 0),
+                    }
+        tr.metrics = {
+            "file_bug_free": min_file_nb,
+            "file_smallness": min_file_sm,
+            "functions_bug_free": min_function_nb,
+            "functions_smallness": min_function_sm,
+        }
+        return tr
+
+    def format_llm_message(self, tr: ToolResult) -> str:
+        """Return the worst Halstead offender as an actionable defect description."""
+        if not tr.metrics:
+            return "No Halstead details available"
+
+        metric_name, score = min(tr.metrics.items(), key=lambda x: x[1])
+        is_function_metric = metric_name.startswith("functions_")
+        is_bug_metric = "bug_free" in metric_name
+
+        worst_file = None
+        worst_function = None
+        worst_score = 1.0
+        worst_bugs = None
+        worst_volume = None
+
+        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)
+                    if s < worst_score:
+                        worst_score = s
+                        worst_file = file_name
+                        worst_function = func_name
+                        worst_bugs = func_data.get("bugs")
+                        worst_volume = func_data.get("volume")
+            else:
+                s = file_data.get("bug_free" if is_bug_metric else "smallness", 1.0)
+                if s < worst_score:
+                    worst_score = s
+                    worst_file = file_name
+                    worst_bugs = file_data.get("bugs")
+                    worst_volume = file_data.get("volume")
+
+        if worst_file is None:
+            return f"**{metric_name}** score: {score:.3f}"
+
+        location = f"`{worst_file}` — function `{worst_function}`" if worst_function else f"`{worst_file}`"
+        if is_bug_metric:
+            detail = f" (Halstead bug estimate: {worst_bugs:.3f})" if worst_bugs is not None else ""
+            return (
+                f"{location} has high estimated bug density{detail}\n\n"
+                f"Reduce complexity by extracting helper functions or simplifying logic."
+            )
+        else:
+            detail = f" (volume: {worst_volume:.0f})" if worst_volume is not None else ""
+            return (
+                f"{location} is too large{detail}\n\n"
+                f"Split into smaller functions or modules."
+            )
+
+    def extract_bugs_and_volume(
+        self, values: dict, max_bugs: float, max_volume: float
+    ) -> tuple[float, float]:
+        """Calculates bug-free and smallness scores from Halstead metrics using logistic scoring."""
+        no_bugs_score = score_logistic_variant(values.get("bugs", max_bugs), max_bugs)
+        smallness_score = score_logistic_variant(
+            values.get("volume", max_volume), max_volume
+        )
+        return (no_bugs_score, smallness_score)

py_cq/parsers/interrogateparser.py

@@ -0,0 +1,58 @@
+"""Parses output from interrogate into a standardized ToolResult.
+
+Interrogate is invoked with ``-v --fail-under 0``, producing a table of
+per-file docstring coverage on stdout::
+
+    | src/foo.py  |  5 |  2 |  60% |
+    | TOTAL       |  5 |  2 |  60% |
+
+The parser extracts per-file coverage and the TOTAL row, storing the TOTAL
+as the ``doc_coverage`` metric (0.0–1.0).
+"""
+
+import re
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+
+_ROW_RE = re.compile(r"^\|\s+(.+?)\s+\|\s+(\d+)\s+\|\s+(\d+)\s+\|\s+(\d+)%\s+\|")
+
+
+class InterrogateParser(AbstractParser):
+    """Parses raw output from ``interrogate -v`` into a ToolResult."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        files: dict[str, dict] = {}
+        total_coverage: float | None = None
+        for line in (raw_result.stdout or "").splitlines():
+            m = _ROW_RE.match(line)
+            if not m:
+                continue
+            name = m.group(1).strip()
+            total = int(m.group(2))
+            miss = int(m.group(3))
+            cover = int(m.group(4))
+            if name == "TOTAL":
+                total_coverage = cover / 100.0
+            elif total > 0:
+                files[name.replace("\\", "/")] = {
+                    "total": total,
+                    "missing": miss,
+                    "coverage": cover / 100.0,
+                }
+        score = total_coverage if total_coverage is not None else 1.0
+        return ToolResult(raw=raw_result, metrics={"doc_coverage": score}, details=files)
+
+    def format_llm_message(self, tr: ToolResult) -> str:
+        score = tr.metrics.get("doc_coverage", 0)
+        uncovered = sorted(
+            [(f, d) for f, d in tr.details.items() if d.get("missing", 0) > 0],
+            key=lambda x: x[1]["coverage"],
+        )[:5]
+        if not uncovered:
+            return f"**doc_coverage** score: {score:.3f}"
+        lines = [f"**doc coverage** {score:.1%} — files with most missing docstrings:"]
+        for path, data in uncovered:
+            miss = data["missing"]
+            pct = data["coverage"]
+            lines.append(f"- `{path}`: {pct:.0%} ({miss} undocumented)")
+        return "\n".join(lines)

py_cq/parsers/maintainabilityparser.py

@@ -0,0 +1,63 @@
+"""Module providing a concrete parser for maintainability analysis tools.
+
+The `MaintainabilityParser` implements the `AbstractParser` interface to
+convert raw JSON output from a maintainability tool into a
+`ToolResult` structure that other components of the framework can consume."""
+
+import json
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import score_logistic_variant
+
+
+class MaintainabilityParser(AbstractParser):
+    """Parses maintainability metrics from raw tool output into :class:`ToolResult` objects.
+
+    This parser consumes the JSON produced by a maintainability analysis tool on
+    ``stdout``. For each file it extracts the maintainability index (`mi`) and
+    rank, converts the index into a normalized score using
+    :func:`score_logistic_variant`, aggregates per-file scores, and returns a
+    :class:`ToolResult` containing an overall maintainability metric and
+    detailed per-file information.
+
+    It implements the :meth:`parse` method required by :class:`AbstractParser`
+    and is intended for use by the framework to transform raw results into a
+    structured format."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parses maintainability metrics from a raw tool result.
+
+        The parser expects the tool to output JSON on ``stdout`` where each key is a file name mapping to a dictionary that contains at least an ``mi`` value (maintainability index) and a ``rank`` string.  If a file entry contains an ``error`` key, that file is recorded with a zero score and the error message.
+
+        For each file with a valid ``mi`` value the method converts the raw maintainability index into a score using :func:`score_logistic_variant`, aggregates the scores, and stores per-file details.  The overall maintainability metric for the tool is then calculated as the average score across all processed files.
+
+        Args:
+            raw_result (RawResult): The raw result object produced by the underlying maintainability tool.
+                It must provide a ``stdout`` attribute containing a JSON string and a ``return_code`` attribute.
+
+        Returns:
+            ToolResult: A structured result object containing:
+                * ``metrics['maintainability']`` - the average score of all processed files (or ``0.0`` if none were processed).
+                * ``details`` - a mapping from each file name (converted to use forward slashes) to a dictionary with keys ``mi``, ``rank``, and optionally ``error``.
+                * ``details['return_code']`` - the tool's exit code."""
+        tr = ToolResult(raw=raw_result)
+        data = json.loads(raw_result.stdout)
+        num_items = 0
+        score = 0
+        for file, values in data.items():
+            if "error" in values:
+                tr.details[file.replace("\\", "/")] = {
+                    "mi": 0.0,
+                    "rank": "F",
+                    "error": values["error"],
+                }
+            elif "mi" in values:
+                file_score = score_logistic_variant(100 - values["mi"], 85)
+                score += file_score
+                num_items += 1
+                tr.details[file.replace("\\", "/")] = {
+                    "mi": file_score,
+                    "rank": values["rank"],
+                }
+        tr.metrics["maintainability"] = score / num_items if num_items > 0 else 0.0
+        return tr

py_cq/parsers/pytestparser.py

@@ -0,0 +1,81 @@
+"""Parses pytest test run output into a standardized :class:`ToolResult`.
+
+This module provides :class:`PytestParser`, a concrete implementation of
+:class:`AbstractParser` that consumes a :class:`RawResult` produced by a pytest
+invocation and returns a :class:`ToolResult` instance.  The parser extracts
+per-test statuses, calculates the overall pass rate, and attaches the
+process return code so downstream components can uniformly consume results
+from multiple test tools.  It is part of the test-collection framework and
+enables consistent handling of pytest output across the system."""
+
+import re
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+
+
+class PytestParser(AbstractParser):
+    """Parses raw pytest output into a structured `ToolResult`.
+
+    Transforms the low-level output from a pytest run into a `ToolResult` that includes pass-rate metrics and detailed per-file test information, enabling downstream components to consume test metrics in a consistent, typed format. Inherits from `AbstractParser` to integrate with the existing parsing framework."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parse pytest raw output into a structured ToolResult.
+
+        This method transforms the textual output of a pytest run into a
+        :class:`ToolResult` object containing two pieces of information:
+
+        * ``metrics['tests']`` - the fraction of tests that passed (``0`` when no
+          tests were executed).
+        * ``details`` - a mapping from each test file to the names of the
+          tests defined in that file and their status (`PASSED`, `FAILED`, etc.).
+          The dictionary also includes the process ``return_code`` for
+          downstream consumers.
+
+        The method splits ``raw_result.stdout`` into lines, checks for the
+        ``'no tests ran'`` sentinel, then uses a regular expression to locate
+        ``<file>::<test_name> <status>`` patterns.  It counts the total number of
+        tests and the number of passed tests to compute the pass-rate metric.
+
+        Args:
+            raw_result (RawResult): Raw output produced by a pytest run,
+                containing ``stdout`` and ``return_code``.
+
+        Returns:
+            ToolResult: A structured result that includes a ``tests`` metric
+            and a ``details`` dictionary as described above.
+
+        Raises:
+            None.  The method never raises an exception; it gracefully handles
+            malformed input by treating it as no tests were run."""
+        # Simplified parsing - replace with actual logic
+        lines = raw_result.stdout.splitlines()
+        tr = ToolResult(raw=raw_result)
+        if "no tests ran" in raw_result.stdout:
+            pass
+        else:
+            tests_found = dict()
+            num_tests = 0
+            passed_tests = 0
+            for line in lines:
+                # tests/test_common.py::test_name[param] PASSED    [ 8%]
+                tests_match = re.search(r"(.*\.py)::([\w\[\].,+\- ]+) (PASSED|FAILED|ERROR|SKIPPED|XFAIL|XPASS)", line)
+                if tests_match:
+                    test_file = tests_match.group(1)
+                    test_name = tests_match.group(2).strip()
+                    test_status = tests_match.group(3)
+                    tests_found.setdefault(test_file, {})[test_name] = test_status
+                    num_tests += 1
+                    if test_status == "PASSED":
+                        passed_tests += 1
+            tr.metrics["tests"] = passed_tests / num_tests if num_tests else 0
+            tr.details = tests_found
+        return tr
+
+    def format_llm_message(self, tr: ToolResult) -> str:
+        """Return the first failing test as a defect description."""
+        for file, tests in tr.details.items():
+            if isinstance(tests, dict):
+                for test_name, status in tests.items():
+                    if status == "FAILED":
+                        return f"`{file}::{test_name}` — test **FAILED**"
+        return "pytest reported failures (no details available)"

py_cq/parsers/ruffparser.py

@@ -0,0 +1,61 @@
+"""Parses output from ruff check into a standardized ToolResult.
+
+This module defines :class:`RuffParser`, an implementation of
+:class:`~.AbstractParser` that converts the raw stdout produced by
+``ruff check --output-format concise`` into a :class:`~.ToolResult`.
+
+The concise output format is one violation per line::
+
+    <file>:<line>:<col>: <CODE> <message>
+
+followed by a summary line ``Found N error.`` or ``All checks passed!``."""
+
+import re
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import read_source_lines, score_logistic_variant
+
+_DIAG_RE = re.compile(r"^(.+):(\d+):(\d+): ([A-Z]\d+) (.+)$")
+
+
+class RuffParser(AbstractParser):
+    """Parses raw output from ``ruff check`` into a structured ToolResult."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        """Parse concise ruff output and return a ToolResult.
+
+        Args:
+            raw_result: Raw output from ``ruff check --output-format concise``.
+
+        Returns:
+            ToolResult with a ``lint`` metric in [0, 1] and per-file violations in details.
+        """
+        files: dict[str, list] = {}
+        for line in (raw_result.stdout or "").splitlines():
+            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),
+                })
+        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) -> 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()))
+        issue = issues[0]
+        line = issue.get("line", "?")
+        code = issue.get("code", "")
+        message = issue.get("message", "")
+        context_start = max(1, line - 3) if isinstance(line, int) else line
+        raw_lines = read_source_lines(file, context_start, count=8).splitlines() if isinstance(line, int) else []
+        src = "\n".join(f"{context_start + i}: {rline}" for i, rline in enumerate(raw_lines)) if raw_lines else ""
+        code_block = f"\n```python\n{src}\n```" if src else ""
+        return f"`{file}:{line}` — **{code}**: {message}{code_block}"

py_cq/parsers/typarser.py

@@ -0,0 +1,65 @@
+"""Parses output from the ty type checker into a standardized ToolResult.
+
+This module defines :class:`TyParser`, an implementation of
+:class:`~.AbstractParser` that converts the raw stdout produced by
+``ty check --output-format concise`` into a :class:`~.ToolResult`.
+
+The concise output format is one diagnostic per line::
+
+    <file>:<line>:<col>: <severity>[<code>] <message>
+
+followed by a summary line ``Found N diagnostic`` or ``All checks passed!``.
+Errors count more heavily than warnings toward the score."""
+
+import re
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import read_source_lines, score_logistic_variant
+
+_DIAG_RE = re.compile(r"^(.+):(\d+):\d+:\s+(error|warning)\[([^\]]+)\] (.+)$")
+
+
+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] = {}
+        weighted = 0
+        for line in (raw_result.stdout or "").splitlines():
+            m = _DIAG_RE.match(line)
+            if m:
+                path = m.group(1).replace("\\", "/")
+                severity = m.group(3)
+                files.setdefault(path, []).append({
+                    "line": int(m.group(2)),
+                    "code": m.group(4),
+                    "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)
+
+    def format_llm_message(self, tr: ToolResult) -> 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()))
+        issue = issues[0]
+        line = issue.get("line", "?")
+        code = issue.get("code", "")
+        message = issue.get("message", "")
+        context_start = max(1, line - 3) if isinstance(line, int) else line
+        raw_lines = read_source_lines(file, context_start, count=8).splitlines() if isinstance(line, int) else []
+        src = "\n".join(f"{context_start + i}: {rline}" for i, rline in enumerate(raw_lines)) if raw_lines else ""
+        code_block = f"\n```python\n{src}\n```" if src else ""
+        return f"`{file}:{line}` — **{code}**: {message}{code_block}"

py_cq/parsers/vultureparser.py

@@ -0,0 +1,48 @@
+"""Parses output from vulture dead-code detector into a standardized ToolResult.
+
+Vulture is invoked with ``--min-confidence 80``, producing one text line
+per unused symbol::
+
+    src/foo.py:10: unused function 'bar' (80% confidence)
+
+The parser counts violations and converts the count into a logistic-variant
+score stored under the ``dead_code`` metric key.
+"""
+
+import re
+
+from py_cq.localtypes import AbstractParser, RawResult, ToolResult
+from py_cq.parsers.common import score_logistic_variant
+
+_LINE_RE = re.compile(r"^(.+):(\d+): (unused \S+) '(.+)' \((\d+)% confidence\)$")
+
+
+class VultureParser(AbstractParser):
+    """Parses raw text output from ``vulture`` into a ToolResult."""
+
+    def parse(self, raw_result: RawResult) -> ToolResult:
+        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)),
+                })
+        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) -> str:
+        if not tr.details:
+            return "vulture reported issues (no details available)"
+        file, issues = next(iter(tr.details.items()))
+        issue = issues[0]
+        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)"

py_cq/storage.py

@@ -0,0 +1,27 @@
+"""Utilities for persisting combined tool results.
+
+This module provides a single helper function, :func:`save_result`, which
+serializes a :class:`CombinedToolResults` instance to a JSON file. The
+function ensures that the target directory exists, writes a readable
+representation of the results, and returns the absolute path of the created
+file.
+
+Example
+-------
+>>> from your_package import CombinedToolResults, save_result
+>>> results = CombinedToolResults(...)
+>>> output_path = save_result(results, "output.json")
+>>> print(output_path)"""
+
+import json
+
+from py_cq.localtypes import CombinedToolResults
+
+
+def save_result(combined_tool_results: CombinedToolResults, file_name: str):
+    """Saves combined tool results to a JSON file named by `file_name`."""
+    if not file_name:
+        return
+    data = combined_tool_results.to_dict()
+    with open(file_name, "w") as f:
+        json.dump(data, f, indent=4)

py_cq/tool_registry.py

@@ -0,0 +1,36 @@
+"""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."""
+
+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 tools.yaml and return a registry.
+
+    Returns:
+        dict[str, ToolConfig]: A mapping from tool ID to its configuration instance."""
+    yaml_text = files("py_cq.config").joinpath("tools.yaml").read_text(encoding="utf-8")
+    config = yaml.safe_load(yaml_text)
+    registry = {}
+    for tool_id, tool_data in config["tools"].items():
+        # Dynamically import parser class
+        module = import_module(f"py_cq.parsers.{tool_data['parser'].lower()}")
+        parser_class = getattr(module, tool_data["parser"])
+        registry[tool_id] = ToolConfig(
+            name=tool_data["name"],
+            command=tool_data["command"],
+            parser_class=parser_class,
+            priority=tool_data["priority"],
+            warning_threshold=tool_data["warning_threshold"],
+            error_threshold=tool_data["error_threshold"],
+            run_in_target_env=tool_data.get("run_in_target_env", False),
+            extra_deps=tool_data.get("extra_deps", []),
+        )
+    return registry
+
+
+tool_registry = load_tool_configs()