python-linters 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

python_linters/baseline_report.py

@@ -0,0 +1,199 @@
+"""`lint --baseline REF`: report only findings new since a git ref.
+
+Ported from the baseline mode of the semgrep-wrapping gate script, minus
+semgrep.
+
+Mechanism:
+1. Resolve *ref* to a SHA with `git rev-parse --verify` (a bad ref, or a
+   project outside any git repo, fails here).
+2. Lint the current tree first, so its resolved ty environment is known.
+3. Check out that SHA into a fresh `git worktree add --detach` scratch
+   directory — never a reused directory, which can carry stale files from
+   an earlier run.
+4. Lint the same sub-path inside the worktree, with the same `--skip` set.
+   ty's `.venv` discovery has nothing to find in a fresh worktree, so the
+   baseline run gets `--python` forwarded explicitly: the caller's own
+   `--python` if given, otherwise the current run's resolved
+   `ty-environment.python_environment`.
+5. Drop every current finding whose (file, rule, message) triple also
+   appears at the baseline. The line number is excluded from this key on
+   purpose: a finding does not become "new" just because a line was
+   inserted above it in the diff's range.
+6. Remove the worktree in `finally`, even on a lint failure or a Ctrl-C.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from python_linters.lint_report import TOOL_NAMES, build_report
+
+# Resolved once to a full path: a bare "git" is a partial-executable-path
+# finding, and the fallback keeps this working even if `which` ever fails.
+_GIT = shutil.which("git") or "git"
+
+
+class BaselineError(Exception):
+    """A baseline ref could not be resolved, or project_path is not in a git repo."""
+
+
+def _resolve_ref(project_path: Path, ref: str) -> str:
+    result = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]  # fixed argv list built by this package, never shell-interpolated or from untrusted input
+        [_GIT, "-C", str(project_path), "rev-parse", "--verify", ref],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        msg = f"cannot resolve baseline ref '{ref}': {result.stderr.strip()}"
+        raise BaselineError(msg)
+    return result.stdout.strip()
+
+
+def _git_root(project_path: Path) -> Path:
+    result = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]  # fixed argv list built by this package, never shell-interpolated or from untrusted input
+        [_GIT, "-C", str(project_path), "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return Path(result.stdout.strip())
+
+
+def _triple(file: str, rule: str, message: str) -> tuple[str, str, str]:
+    return (file, rule, message)
+
+
+def _baseline_triples(report: dict[str, object]) -> set[tuple[str, str, str]]:
+    triples: set[tuple[str, str, str]] = set()
+    for tool in TOOL_NAMES:
+        section = report.get(tool)
+        if not isinstance(section, dict):
+            continue
+        for rule, group in section.items():
+            triples.update(
+                _triple(loc["file"], rule, loc["message"]) for loc in group["locations"]
+            )
+    return triples
+
+
+def _diff_report(
+    report: dict[str, object], baseline_triples: set[tuple[str, str, str]]
+) -> tuple[dict[str, object], int]:
+    """Keep only locations whose triple is not in *baseline_triples*.
+
+    Recomputes each kept rule's `count` and each tool's `summary` entry;
+    drops a rule whose locations list becomes empty.
+    """
+    new_report = dict(report)
+    summary: dict[str, object] = {}
+    grand_total = 0
+
+    for tool in TOOL_NAMES:
+        section = report.get(tool)
+        if not isinstance(section, dict):
+            continue
+
+        new_section: dict[str, dict[str, object]] = {}
+        counts: dict[str, int] = {}
+        for rule, group in section.items():
+            keep = [
+                loc
+                for loc in group["locations"]
+                if _triple(loc["file"], rule, loc["message"]) not in baseline_triples
+            ]
+            if not keep:
+                continue
+            new_group = dict(group)
+            new_group["locations"] = keep
+            new_group["count"] = len(keep)
+            new_section[rule] = new_group
+            counts[rule] = len(keep)
+
+        new_report[tool] = new_section
+        total = sum(counts.values())
+        summary[tool] = {"total": total, "rules": len(new_section)}
+        grand_total += total
+
+    new_report["summary"] = summary
+    return new_report, grand_total
+
+
+def run_with_baseline(
+    project_path: Path,
+    baseline_ref: str,
+    skip: frozenset[str] = frozenset(),
+    ty_python: str | None = None,
+    ty_extra_search_paths: tuple[str, ...] = (),
+) -> tuple[dict[str, object], int]:
+    """Lint *project_path*, then drop every finding already present at
+    *baseline_ref*. Returns the same report shape as `build_report`, plus a
+    top-level `"baseline"` key, with the summary and total counting only
+    the new findings.
+
+    Raises `BaselineError` if the ref does not resolve or project_path is
+    not inside a git repo.
+    """
+    sha = _resolve_ref(project_path, baseline_ref)
+    git_root = _git_root(project_path)
+    try:
+        rel_to_root = project_path.relative_to(git_root)
+    except ValueError:
+        rel_to_root = Path()
+
+    current_report, _ = build_report(
+        project_path,
+        skip=skip,
+        ty_python=ty_python,
+        ty_extra_search_paths=ty_extra_search_paths,
+    )
+
+    # The baseline worktree has no `.venv` of its own to discover: forward
+    # the current run's resolved ty environment, unless the caller already
+    # pinned one explicitly.
+    baseline_ty_python = ty_python
+    if baseline_ty_python is None and "ty" not in skip:
+        ty_environment = current_report.get("ty-environment", {})
+        baseline_ty_python = (
+            ty_environment.get("python_environment")
+            if isinstance(ty_environment, dict)
+            else None
+        )
+
+    tmpdir = tempfile.mkdtemp(prefix="python-linters-baseline-")
+    try:
+        worktree = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]  # fixed argv list built by this package, never shell-interpolated or from untrusted input
+            [_GIT, "-C", str(project_path), "worktree", "add", "--detach", tmpdir, sha],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if worktree.returncode != 0:
+            msg = f"git worktree add failed: {worktree.stderr.strip()}"
+            raise BaselineError(msg)
+
+        baseline_path = Path(tmpdir) / rel_to_root
+        baseline_report, _ = build_report(
+            baseline_path,
+            skip=skip,
+            ty_python=baseline_ty_python,
+            ty_extra_search_paths=ty_extra_search_paths,
+        )
+    finally:
+        subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]  # fixed argv list built by this package, never shell-interpolated or from untrusted input
+            [_GIT, "-C", str(project_path), "worktree", "remove", "--force", tmpdir],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+    baseline_triples = _baseline_triples(baseline_report)
+    new_report, total = _diff_report(current_report, baseline_triples)
+    new_report["baseline"] = {"ref": baseline_ref, "sha": sha}
+    if baseline_ty_python is not None:
+        new_report["baseline"]["ty-python"] = baseline_ty_python
+    return new_report, total

python_linters/cli_commands.py

@@ -5,30 +5,54 @@ import json
 import sys
 from pathlib import Path
 
+from python_linters.baseline_report import BaselineError, run_with_baseline
 from python_linters.config_check import (
     check_ruff_config,
     check_ty_config,
     format_ruff_report,
     format_ty_report,
 )
-from python_linters.lint_report import build_report
+from python_linters.lint_report import TOOL_NAMES, build_report
 from python_linters.reference_files import reference_text
+from python_linters.text_report import format_text_report
 from python_linters.tool_errors import ToolFailedError
+from python_linters.tool_versions import package_version, tool_versions
 
 
 def _lint(args: argparse.Namespace) -> int:
+    if set(args.skip) >= set(TOOL_NAMES):
+        args.parser.error("--skip cannot skip every tool")
+
     project_path = Path(args.path).resolve()
     if not project_path.exists():
         print(f"Error: {project_path} does not exist", file=sys.stderr)
         return 2
 
     try:
-        output, total_findings = build_report(project_path)
-    except ToolFailedError as e:
+        if args.baseline:
+            output, total_findings = run_with_baseline(
+                project_path,
+                args.baseline,
+                skip=frozenset(args.skip),
+                ty_python=args.ty_python,
+                ty_extra_search_paths=tuple(args.ty_extra_search_path),
+            )
+        else:
+            output, total_findings = build_report(
+                project_path,
+                skip=frozenset(args.skip),
+                ty_python=args.ty_python,
+                ty_extra_search_paths=tuple(args.ty_extra_search_path),
+            )
+    except (ToolFailedError, BaselineError) as e:
         print(str(e), file=sys.stderr)
         return 2
 
-    serialized = json.dumps(output, indent=2)
+    serialized = (
+        format_text_report(output)
+        if args.format == "text"
+        else json.dumps(output, indent=2)
+    )
 
     if args.out:
         Path(args.out).write_text(serialized, encoding="utf-8")
@@ -39,6 +63,11 @@ def _lint(args: argparse.Namespace) -> int:
     return 1 if total_findings else 0
 
 
+def _version_text() -> str:
+    tools = ", ".join(f"{name} {v}" for name, v in tool_versions().items())
+    return f"python-linters {package_version()} ({tools})"
+
+
 def _reference(args: argparse.Namespace) -> int:
     print(reference_text(args.tool), end="")
     return 0
@@ -72,6 +101,12 @@ def _check_config(args: argparse.Namespace) -> int:
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="python-linters")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=_version_text(),
+        help="print this package's version and its bundled ruff/ty/pymodularity versions",
+    )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     lint_parser = subparsers.add_parser(
@@ -79,7 +114,39 @@ def build_parser() -> argparse.ArgumentParser:
     )
     lint_parser.add_argument("path", nargs="?", default=".")
     lint_parser.add_argument("--out", default=None)
-    lint_parser.set_defaults(func=_lint)
+    lint_parser.add_argument(
+        "--format",
+        choices=["json", "text"],
+        default="json",
+        help="json (default) or one finding per line, sorted by file then line",
+    )
+    lint_parser.add_argument(
+        "--skip",
+        action="append",
+        default=[],
+        choices=list(TOOL_NAMES),
+        help="skip this tool (repeatable); skipping all 4 is an error",
+    )
+    lint_parser.add_argument(
+        "--python",
+        dest="ty_python",
+        default=None,
+        help="forwarded verbatim as ty check's --python",
+    )
+    lint_parser.add_argument(
+        "--extra-search-path",
+        dest="ty_extra_search_path",
+        action="append",
+        default=[],
+        help="forwarded verbatim as ty check's --extra-search-path (repeatable)",
+    )
+    lint_parser.add_argument(
+        "--baseline",
+        default=None,
+        help="git ref: report only findings new since this ref "
+        "(identity: file, rule, message — line excluded)",
+    )
+    lint_parser.set_defaults(func=_lint, parser=lint_parser)
 
     reference_parser = subparsers.add_parser(
         "reference", help="print a shipped reference config to stdout"

python_linters/lint_report.py

@@ -1,12 +1,20 @@
-"""Run ruff, ty and pymodularity and group their findings by rule.
+"""Run ruff, ruff format --check, ty and pymodularity and group their findings by rule.
 
 Ported from lint_grouped.py (quality-and-security-tools howtos), minus eslint.
 
 Output structure:
     {
       "project": "/abs/path",
+      "tools": {"ruff": "0.17.5", "ty": "0.0.103", "pymodularity": "0.5.0"},
+      "skipped": ["pymodularity"],
+      "ty-environment": {
+        "project_root": "/abs/path",
+        "python_environment": "/abs/path/.venv",
+        "pythonpath": "/abs/legacy-copy"
+      },
       "summary": {
         "ruff":        {"total": 100, "rules": 12},
+        "ruff-format": {"total": 2,   "rules": 1},
         "ty":          {"total": 50,  "rules": 8},
         "pymodularity": {"total": 5,  "rules": 2}
       },
@@ -17,6 +25,12 @@ Output structure:
           "locations": [{"file": "rel/path.py", "line": 12, "col": 5, "message": "..."}, ...]
         }
       },
+      "ruff-format": {
+        "unformatted": {
+          "count":     2,
+          "locations": [{"file": "rel/path.py", "line": 1, "col": 1, "message": "would be reformatted"}, ...]
+        }
+      },
       "ty": {
         "invalid-return-type": {
           "severity":  "major",
@@ -34,24 +48,52 @@ Output structure:
     }
 
 Rules are sorted by count (descending) so the most common issues come first.
+
+`ty-environment` is present only when ty itself ran (absent if "ty" is in
+`skipped`); its `pythonpath` key is present only when `PYTHONPATH` was set.
+A skipped tool gets no `summary` entry and no section of its own.
 """
 
 from __future__ import annotations
 
 import json
 import os
+import re
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from python_linters.tool_errors import run_checked
+from python_linters.tool_errors import ToolFailedError, run_checked
+from python_linters.tool_versions import tool_versions
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
 _TY_SEVERITY_MAP = {"major": "error", "minor": "warning", "info": "info"}
 
+# Matches ruff format --check's per-file location line, e.g.:
+#  --> my_package/main_module.py:1:2
+_RUFF_FORMAT_LOCATION_RE = re.compile(r"^ --> (?P<file>.+):(?P<line>\d+):(?P<col>\d+)$")
+
+# `ty check -vv`'s DEBUG lines that name the project root it resolved.
+# "Found project at" fires when the root differs from (or has its own
+# `tool.ty` config at) the searched path; "Project without `tool.ty`
+# section" fires when ty found no config and settled on the searched path
+# itself. Either line, found first, names the actual root.
+_TY_FOUND_PROJECT_RE = re.compile(r"Found project at '(?P<root>[^']+)'")
+_TY_PROJECT_WITHOUT_CONFIG_RE = re.compile(
+    r"Project without `tool\.ty` section: '(?P<root>[^']+)'"
+)
+
+# `ty check -vv`'s DEBUG line that names the sys.prefix of the Python
+# environment it actually resolved for import resolution — the same line
+# fires whether that environment came from VIRTUAL_ENV, a discovered
+# `.venv`, or an explicit `--python`.
+_TY_SYS_PREFIX_RE = re.compile(
+    r"Searching for site-packages directory in sys\.prefix (?P<prefix>\S+)"
+)
+
 
 @dataclass
 class Location:
@@ -120,7 +162,7 @@ def run_ruff(project_path: Path) -> dict[str, FindingGroup]:
     # Resolution: the python-linters environment's own pinned ruff, run as
     # `sys.executable -m ruff` so it never falls through to PATH. In
     # dev-dependency mode that environment is the linted project's venv, so
-    # ruff==0.17.3 (pinned in python-linters' own pyproject.toml) is what
+    # ruff==0.17.5 (pinned in python-linters' own pyproject.toml) is what
     # actually runs — never a PATH ruff of another version, which lints
     # with other rules and may refuse the reference config.
     #
@@ -161,7 +203,96 @@ def run_ruff(project_path: Path) -> dict[str, FindingGroup]:
     return _group_findings(findings())
 
 
-def run_ty(project_path: Path) -> dict[str, FindingGroup]:
+def run_ruff_format(project_path: Path) -> dict[str, FindingGroup]:
+    # Resolution: same as run_ruff above — `sys.executable -m ruff`, never
+    # PATH, `--no-cache` so a read-only linted project tree is never an
+    # issue.
+    #
+    # `ruff format --check` has no JSON output mode (unlike `ruff check`):
+    # `ruff format --help` lists `--output-format` only under `check`, not
+    # under `format`. Its human-readable stdout does carry one `-->
+    # path:line:col` line per unformatted file, which is parsed below
+    # instead.
+    #
+    # ruff format's exit codes: 0 all formatted, 1 some file would be
+    # reformatted, 2 tool failure (bad config, crash, ...). A failure must
+    # never read as "0 findings" — `run_checked` raises instead of
+    # returning in that case.
+    result = run_checked(
+        [sys.executable, "-m", "ruff", "format", "--check", "--no-cache", "."],
+        project_path,
+        "ruff-format",
+        ok_codes=(0, 1),
+    )
+    if not result.stdout.strip():
+        return {}
+
+    def findings() -> Iterable[_Finding]:
+        for line in result.stdout.splitlines():
+            match = _RUFF_FORMAT_LOCATION_RE.match(line)
+            if match is None:
+                continue
+            location = Location(
+                file=_relative_to(match["file"], project_path),
+                line=int(match["line"]),
+                col=int(match["col"]),
+                message="would be reformatted",
+            )
+            yield "unformatted", None, None, location
+
+    groups = _group_findings(findings())
+    # Exit 1 with nothing parsed means ruff changed its text output: fail
+    # loudly instead of reporting a clean project.
+    if result.returncode == 1 and not groups:
+        detail = f"exit 1 but no ' --> path:line:col' line parsed:\n{result.stdout}"
+        tool = "ruff-format"
+        raise ToolFailedError(tool, detail)
+    return groups
+
+
+def _parse_ty_environment(stderr: str) -> dict[str, str]:
+    """Pull ty's resolved project root and Python environment out of its
+    `-vv` DEBUG log lines.
+
+    ty prints no structured ("--output-format json"-style) way to ask for
+    this, so the log lines are the only source. Both a project root line
+    and a sys.prefix line are expected on every run (see the regex
+    docstrings above) — their absence means ty changed its logging, so
+    this fails loudly instead of reporting a guessed or stale environment.
+    """
+    environment: dict[str, str] = {}
+
+    root_match = _TY_FOUND_PROJECT_RE.search(
+        stderr
+    ) or _TY_PROJECT_WITHOUT_CONFIG_RE.search(stderr)
+    if root_match is None:
+        tool = "ty"
+        detail = f"-vv output named no project root; ty may have changed its logging:\n{stderr}"
+        raise ToolFailedError(tool, detail)
+    environment["project_root"] = root_match["root"]
+
+    prefix_match = _TY_SYS_PREFIX_RE.search(stderr)
+    if prefix_match is None:
+        tool = "ty"
+        detail = (
+            "-vv output named no resolved Python environment; ty may have "
+            f"changed its logging:\n{stderr}"
+        )
+        raise ToolFailedError(tool, detail)
+    environment["python_environment"] = prefix_match["prefix"]
+
+    pythonpath = os.environ.get("PYTHONPATH", "")
+    if pythonpath != "":
+        environment["pythonpath"] = pythonpath
+
+    return environment
+
+
+def run_ty(
+    project_path: Path,
+    python: str | None = None,
+    extra_search_paths: tuple[str, ...] = (),
+) -> tuple[dict[str, FindingGroup], dict[str, str]]:
     # Resolution: `sys.executable -m ty` from the python-linters
     # environment, never a bare `ty` entry point (that one falls through to
     # PATH when the environment has no ty on it) and never a PATH `ty`.
@@ -188,16 +319,35 @@ def run_ty(project_path: Path) -> dict[str, FindingGroup]:
     # VIRTUAL_ENV here makes ty fall through to discovering `.venv` under
     # project_path itself. In dev-dependency mode this is a no-op: there
     # the project's own venv was VIRTUAL_ENV already.
+    #
+    # `--python`/`--extra-search-path` let a caller override this
+    # discovery outright — needed e.g. for a ROS 2 package that resolves
+    # its imports from a system interpreter and `/opt/ros/...`, never a
+    # `.venv` under the linted path.
+    #
+    # `-vv`: only source for ty's resolved project root and Python
+    # environment (see `_parse_ty_environment`). Its DEBUG lines go to
+    # stderr, never stdout, so the `--output-format gitlab` JSON below is
+    # unaffected.
     ty_env = {k: v for k, v in os.environ.items() if k != "VIRTUAL_ENV"}
+    cmd = [sys.executable, "-m", "ty", "check", "--output-format", "gitlab", "-vv"]
+    if python is not None:
+        cmd += ["--python", python]
+    for search_path in extra_search_paths:
+        cmd += ["--extra-search-path", search_path]
+    cmd.append(".")
+
     result = run_checked(
-        [sys.executable, "-m", "ty", "check", "--output-format", "gitlab", "."],
+        cmd,
         project_path,
         "ty",
         ok_codes=(0, 1),
         env=ty_env,
     )
+    ty_environment = _parse_ty_environment(result.stderr)
+
     if not result.stdout.strip():
-        return {}
+        return {}, ty_environment
 
     diagnostics = json.loads(result.stdout)
 
@@ -228,7 +378,7 @@ def run_ty(project_path: Path) -> dict[str, FindingGroup]:
             )
             yield rule, None, severity, location
 
-    return _group_findings(findings())
+    return _group_findings(findings()), ty_environment
 
 
 def run_pymodularity(project_path: Path) -> dict[str, FindingGroup]:
@@ -274,19 +424,38 @@ def run_pymodularity(project_path: Path) -> dict[str, FindingGroup]:
     return _group_findings(findings())
 
 
-def build_report(project_path: Path) -> tuple[dict[str, object], int]:
+# The 4 tools `lint` can run, in report order. Shared with the CLI's
+# `--skip` choices so the two never drift apart.
+TOOL_NAMES = ("ruff", "ruff-format", "ty", "pymodularity")
+
+
+def build_report(
+    project_path: Path,
+    skip: frozenset[str] = frozenset(),
+    ty_python: str | None = None,
+    ty_extra_search_paths: tuple[str, ...] = (),
+) -> tuple[dict[str, object], int]:
     """Return the JSON-ready report and the total finding count across all tools."""
     summary: dict[str, object] = {}
     sections: dict[str, object] = {}
     grand_total = 0
+    ty_environment: dict[str, str] = {}
+
+    for tool in TOOL_NAMES:
+        if tool in skip:
+            continue
 
-    for tool, run in (
-        ("ruff", run_ruff),
-        ("ty", run_ty),
-        ("pymodularity", run_pymodularity),
-    ):
         print(f"Running {tool} on {project_path} ...", file=sys.stderr)
-        violations = run(project_path)
+        if tool == "ruff":
+            violations = run_ruff(project_path)
+        elif tool == "ruff-format":
+            violations = run_ruff_format(project_path)
+        elif tool == "ty":
+            violations, ty_environment = run_ty(
+                project_path, python=ty_python, extra_search_paths=ty_extra_search_paths
+            )
+        else:
+            violations = run_pymodularity(project_path)
         total = sum(group.count for group in violations.values())
         print(f"  {total} violations across {len(violations)} rules", file=sys.stderr)
 
@@ -294,5 +463,13 @@ def build_report(project_path: Path) -> tuple[dict[str, object], int]:
         sections[tool] = {rule: group.to_dict() for rule, group in violations.items()}
         grand_total += total
 
-    report = {"project": str(project_path), "summary": summary, **sections}
+    report: dict[str, object] = {
+        "project": str(project_path),
+        "tools": tool_versions(),
+        "skipped": sorted(skip),
+    }
+    if ty_environment:
+        report["ty-environment"] = ty_environment
+    report["summary"] = summary
+    report.update(sections)
     return report, grand_total

python_linters/references/ruff.reference.toml

@@ -12,7 +12,7 @@
 #   5. flake8-type-checking — list your runtime-evaluated base classes and
 #                           decorators (pydantic, FastAPI preset)
 #
-# Last triaged against: ruff 0.17.3
+# Last triaged against: ruff 0.17.5
 # Rule names in `select`/`ignore` and in `# ruff: ignore[...]` comments need
 # `preview = true`: without it ruff rejects the config and treats name-based
 # suppression comments as inert.
@@ -20,7 +20,7 @@
 
 # Older ruff fails on the first rule name it does not know, with a cryptic
 # `Unknown rule selector`. This guard names the version instead.
-required-version = ">=0.17.3"
+required-version = ">=0.17.5"
 
 target-version = "py312"
 
@@ -94,6 +94,8 @@ select = [
 
     # ── Security ──
     "S",     # flake8-bandit — security antipatterns (hardcoded passwords, exec, …)
+    "tarfile-ignore-zeros-true",  # code-less rule: `ignore_zeros=True` reads past the
+                                  #   end-of-archive marker, so appended members get extracted too
     "EXE",   # flake8-executable — shebang correctness
 
     # ── Error handling ──
@@ -170,11 +172,11 @@ select = [
 
     # ── Preview rules, selected by name ──────────────────────────────────
     # `explicit-preview-rules = true`: a category select above turns on only its
-    # stable rules. Each preview rule below was triaged on ruff 0.17.3.
+    # stable rules. Each preview rule below was triaged on ruff 0.17.5.
     # A preview rule in a selected category that is neither listed
     # here nor covered by an `# excluded` line below is untriaged.
 
-    # Ruff-specific (25)
+    # Ruff-specific (26)
     # bugs: the code runs but does the wrong thing
     "missing-f-string-syntax",          # `"{x}"` without `f` prints the braces
     "unraw-re-pattern",                 # `"\b"` in a non-raw pattern is a backspace, not a word boundary, and nothing else warns
@@ -204,13 +206,15 @@ select = [
     "noqa-comments",
     "rule-codes-in-suppression-comments",
     "rule-codes-in-selectors",
+    "renamed-rule",                     # a config selector that only works through a rename redirect
 
-    # Pylint (18)
+    # Pylint (19)
     # bugs: runtime errors or silently lost behavior
     "dict-iter-missing-items",          # `for k, v in d` unpacks keys, not items
     "modified-iterating-set",           # RuntimeError
     "redefined-slots-in-subclass",      # makes the base class slot unreachable
     "bad-dunder-method-name",           # a misspelled dunder is never called
+    "no-method-argument",               # a method without `self`/`cls` raises TypeError when called on an instance
     "unspecified-encoding",             # `open()` without encoding uses the platform locale
     # size and nesting limits, every threshold set under [lint.pylint]
     "too-many-public-methods",
@@ -262,9 +266,11 @@ select = [
     "deprecated-abc-decorator",         # deprecated since 3.3
     "context-manager-iterator",         # @contextmanager needs Generator, Iterator lacks `throw`
 
-    # flake8-async (1): a context manager's cleanup is delayed until the
-    # generator closes, when `await` is no longer allowed
-    "yield-in-context-manager-in-async-generator",
+    # flake8-async (2)
+    "yield-in-context-manager-in-async-generator",  # the context manager's cleanup waits until
+                                                    #   the generator closes, when `await` is no longer allowed
+    "pytest-raises-exception-group",  # `pytest.RaisesGroup` checks the grouped exceptions,
+                                      #   `pytest.raises(ExceptionGroup)` only the wrapper
 
     # flake8-pytest-style (1): `pytest.warns()` without a warning fails at runtime
     "pytest-warns-without-warning",
@@ -391,7 +397,7 @@ ignore = [
                                 #   callers, so its method count is not an
                                 #   interface
     # missing return type — test functions always return None
-    "missing-return-type-undocumented-public-function",
+    "missing-return-type-public-function",
     "import-private-name",  # testing internal functions is legitimate
     "unused-async",  # async test doubles mirror the awaited signature they replace
     "float-equality-comparison",  # asserting an exactly representable result is correct
@@ -408,7 +414,7 @@ ignore = [
     "magic-value-comparison",
     "no-self-use",
     "too-many-public-methods",
-    "missing-return-type-undocumented-public-function",
+    "missing-return-type-public-function",
     "implicit-namespace-package",  # standalone test scripts
     "import-private-name",
     "unused-async",

python_linters/references/ty.reference.toml

@@ -2,7 +2,7 @@
 # ty Reference Configuration
 # ============================================================================
 #
-# Canonical rule table for new Python projects. Every rule ty 0.0.90 knows is
+# Canonical rule table for new Python projects. Every rule ty 0.0.103 knows is
 # listed below, one line each, with no `all = "error"` base. Each line is
 # "error" or "ignore". A "warn" setting is never used, because a warning
 # does not fail a CI gate, so a green run hides it.
@@ -16,8 +16,8 @@
 #   - into `pyproject.toml` under `[tool.ty.rules]` (rename the table header,
 #     keep every line).
 #
-# Last triaged against: ty 0.0.90 (140 rules: 97 error-by-default,
-# 25 warn-by-default, 18 ignore-by-default).
+# Last triaged against: ty 0.0.103 (152 rules: 107 error-by-default,
+# 27 warn-by-default, 18 ignore-by-default).
 #
 # Re-check the copied table after every ty version bump:
 #   python-linters check-config ty <path/to/ty.toml>
@@ -51,7 +51,7 @@ redundant-condition-strict = "ignore"
 # `re.Match.group()`) goes unflagged.
 # Re-triage on each ty bump: ty is 0.0.x and its inference changes.
 unsound-assignment = "ignore"
-unsound-return-statement = "ignore"
+unsound-return = "ignore"
 unsound-yield = "ignore"
 
 # not applicable: checks classes built with `type()`, which the doctrine
@@ -80,66 +80,69 @@ truthiness-test-of-none-union = "error"
 # --- Enforced rules: on by default in ty, alphabetical ----------------------
 
 abstract-and-final-method = "error"
+abstract-class-instantiation = "error"
+abstract-method-call = "error"
 abstract-method-in-final-class = "error"
 ambiguous-protocol-member = "error"
 assert-type-unspellable-subtype = "error"
-call-abstract-method = "error"
-call-non-callable = "error"
-call-top-callable = "error"
+call-to-function-with-unknown-signature = "error"
 conflicting-declarations = "error"
 conflicting-metaclass = "error"
 cyclic-class-definition = "error"
 cyclic-type-alias-definition = "error"
-dataclass-field-order = "error"
 deprecated = "error"
 duplicate-base = "error"
 duplicate-kw-only = "error"
-empty-body = "error"
 escape-character-in-forward-annotation = "error"
 experimental-syntax = "error"
 final-on-non-method = "error"
 final-without-value = "error"
 ignore-comment-unknown-rule = "error"
-implicit-concatenated-string-type-annotation = "error"
+implicit-string-concatenation-in-annotation = "error"
+import-not-found = "error"
+incompatible-attribute-override = "error"
+incompatible-method-override = "error"
+incompatible-mutable-override = "error"
+incompatible-property-override = "error"
 inconsistent-mro = "error"
+inconsistent-overload-decorator = "error"
+inconsistent-overload-implementation = "error"
 index-out-of-bounds = "error"
 ineffective-final = "error"
 instance-layout-conflict = "error"
 invalid-argument-type = "error"
 invalid-assignment = "error"
 invalid-attribute-access = "error"
-invalid-attribute-override = "error"
 invalid-await = "error"
 invalid-base = "error"
 invalid-context-manager = "error"
 invalid-dataclass = "error"
+invalid-dataclass-field-order = "error"
 invalid-dataclass-override = "error"
 invalid-declaration = "error"
 invalid-enum-member-annotation = "error"
 invalid-exception-caught = "error"
 invalid-explicit-override = "error"
+invalid-explicit-return = "error"
 invalid-frozen-dataclass-subclass = "error"
+invalid-generator-return-type = "error"
 invalid-generic-class = "error"
 invalid-generic-enum = "error"
 invalid-ignore-comment = "error"
+invalid-implicit-return = "error"
+invalid-implicit-return-in-function-with-stub-body = "error"
 invalid-init-type-variable = "error"
-invalid-key = "error"
 invalid-legacy-type-variable = "error"
 invalid-match-pattern = "error"
 invalid-metaclass = "error"
-invalid-method-override = "error"
 invalid-module-getattr-call = "error"
-invalid-mutable-override = "error"
 invalid-named-tuple = "error"
 invalid-named-tuple-override = "error"
 invalid-newtype = "error"
-invalid-overload = "error"
 invalid-parameter-default = "error"
 invalid-paramspec = "error"
-invalid-property-type-override = "error"
 invalid-protocol = "error"
 invalid-raise = "error"
-invalid-return-type = "error"
 invalid-super-argument = "error"
 invalid-syntax-in-forward-annotation = "error"
 invalid-total-ordering = "error"
@@ -153,16 +156,24 @@ invalid-type-variable-constraints = "error"
 invalid-type-variable-default = "error"
 invalid-typed-dict-field = "error"
 invalid-typed-dict-header = "error"
+invalid-typed-dict-key = "error"
 invalid-typed-dict-statement = "error"
 invalid-yield = "error"
 isinstance-against-protocol = "error"
 isinstance-against-typed-dict = "error"
+lost-keyword-for-regular-parameter = "error"
 mismatched-type-name = "error"
+misplaced-overload-decorator = "error"
 missing-argument = "error"
+missing-attribute = "error"
+missing-overload-implementation = "error"
 missing-slot = "error"
 missing-typed-dict-key = "error"
+missing-union-attribute = "error"
 no-matching-overload = "error"
 non-callable-init-subclass = "error"
+non-literal-typed-dict-key = "error"
+not-callable = "error"
 not-iterable = "error"
 not-subscriptable = "error"
 override-of-final-method = "error"
@@ -176,7 +187,9 @@ raw-string-type-annotation = "error"
 redundant-cast = "error"
 redundant-condition = "error"
 redundant-final-classvar = "error"
+renamed-rule-in-ignore-comment = "error"
 shadowed-type-variable = "error"
+single-overload = "error"
 static-assert-error = "error"
 subclass-of-dataclass-with-order = "error"
 subclass-of-final-class = "error"
@@ -189,9 +202,8 @@ unavailable-implicit-super-arguments = "error"
 unbound-type-variable = "error"
 undefined-reveal = "error"
 unknown-argument = "error"
-unresolved-attribute = "error"
+unknown-typed-dict-constructor-key = "error"
 unresolved-global = "error"
-unresolved-import = "error"
 unresolved-reference = "error"
 unsupported-base = "error"
 unsupported-bool-conversion = "error"

python_linters/text_report.py

@@ -0,0 +1,54 @@
+"""Render a `build_report` result as one line per finding, for a terminal."""
+
+from __future__ import annotations
+
+from python_linters.lint_report import TOOL_NAMES
+
+
+def format_text_report(report: dict[str, object]) -> str:
+    """One line per finding, sorted by file then line, with a totals line last.
+
+    `file:line:col tool/rule message`, matching how ruff and ty print their
+    own findings — unlike the JSON report, this is for a human reading a
+    terminal, not a script.
+    """
+    rows: list[tuple[str, int, int, str, str, str]] = []
+    for tool in TOOL_NAMES:
+        section = report.get(tool)
+        if not isinstance(section, dict):
+            continue
+        for rule, group in section.items():
+            rows.extend(
+                (
+                    location["file"],
+                    location["line"],
+                    location["col"],
+                    tool,
+                    rule,
+                    location["message"],
+                )
+                for location in group["locations"]
+            )
+
+    rows.sort(key=lambda row: (row[0], row[1]))
+
+    lines = [
+        f"{file}:{line}:{col} {tool}/{rule} {message}"
+        for file, line, col, tool, rule, message in rows
+    ]
+
+    summary_obj = report.get("summary", {})
+    summary: dict[str, dict[str, int]] = (
+        summary_obj if isinstance(summary_obj, dict) else {}
+    )
+    totals = " ".join(f"{tool}={data['total']}" for tool, data in summary.items())
+    grand_total = sum(data["total"] for data in summary.values())
+    totals_line = f"{totals} total={grand_total}" if totals else f"total={grand_total}"
+
+    baseline = report.get("baseline")
+    if isinstance(baseline, dict):
+        totals_line += f" baseline={baseline['ref']}"
+
+    lines.append(totals_line)
+
+    return "\n".join(lines)

python_linters/tool_versions.py

@@ -0,0 +1,22 @@
+"""Resolved versions of this package and the tools it bundles.
+
+Read from `importlib.metadata`, never from a subprocess call: the versions
+are pinned in `pyproject.toml` and installed into the same environment this
+package itself runs in, so the installed-distribution metadata already
+names exactly what `sys.executable -m <tool>` will run.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+TOOL_DISTRIBUTIONS = ("ruff", "ty", "pymodularity")
+
+
+def package_version() -> str:
+    return version("python-linters")
+
+
+def tool_versions() -> dict[str, str]:
+    """Bundled ruff/ty/pymodularity versions, keyed by distribution name."""
+    return {name: version(name) for name in TOOL_DISTRIBUTIONS}

python_linters-0.2.3.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: python-linters
+Version: 0.2.3
+Summary: Run ruff, ty and pymodularity on a Python project and print one JSON report grouped by rule.
+Author: Tilo Himmelsbach
+License-Expression: MIT
+Requires-Dist: ruff==0.17.5
+Requires-Dist: ty==0.0.103
+Requires-Dist: pymodularity==0.5.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# python-linters
+
+Run ruff, ty and pymodularity on a Python project and print one JSON report
+grouped by rule, for agents and CI to read.
+
+## Install
+
+As a dev dependency of the project you want to lint:
+
+```
+uv add --dev python-linters
+```
+
+## Commands
+
+- `uv run python-linters lint [path] [--out FILE] [--format json|text]
+  [--skip TOOL]... [--python PATH] [--extra-search-path DIR]...
+  [--baseline REF]` — runs
+  ruff, `ruff format --check`, ty and pymodularity (default path: `.`) and
+  prints the merged report to stdout, or writes it to `FILE` with `--out`.
+  - `--format text` prints one line per finding (`file:line:col
+    tool/rule message`, sorted by file then line) with a totals line
+    last, instead of the default JSON. `--out` writes whichever format
+    was chosen.
+  - `--skip TOOL` (repeatable; `ruff`, `ruff-format`, `ty`,
+    `pymodularity`) drops that tool: it does not run, gets no section and
+    no summary entry, and is listed under the report's top-level
+    `"skipped"`. Skipping all 4 is a usage error.
+  - `--python PATH` and `--extra-search-path DIR` (repeatable) are
+    forwarded verbatim to `ty check`'s own `--python`/`--extra-search-path`.
+    Needed whenever the project's imports do not resolve from a `.venv`
+    under the linted path — e.g. a ROS 2 package that resolves `rclpy`
+    and friends from a system interpreter and `/opt/ros/...`.
+  - ty looks for a `.venv` at *its own project root* — the directory
+    holding the nearest `ty.toml`, or a `pyproject.toml` with a
+    `[tool.ty]` section — not at the path you pass to `lint`. A shared
+    parent config can point ty's `.venv` search at the wrong directory for
+    a sub-package; the report's `"ty-environment"` key (below) shows what
+    ty actually resolved.
+  - ty ranks `$PYTHONPATH` entries ahead of first-party code. If
+    `PYTHONPATH` is set, a stale installed copy on it can shadow the
+    project tree being linted and silently report 0 findings; the report
+    names it under `"ty-environment"` when set.
+  - the report's top-level `"tools"` key names the bundled ruff/ty/
+    pymodularity versions; `"ty-environment"` names ty's resolved project
+    root and Python environment (absent if `ty` is skipped).
+  - `--baseline REF` (a branch, tag, SHA, `HEAD~N`, ...) reports only
+    findings that are new since that git ref: it checks the ref out into a
+    fresh `git worktree add --detach` scratch directory (never a reused
+    one — a stale copy there can carry findings from an earlier run),
+    lints the same sub-path there, and drops every current finding whose
+    `(file, rule, message)` triple already exists at the baseline. The
+    line number is excluded from that triple on purpose: a finding does
+    not become "new" just because a line was inserted above it. The
+    worktree is removed afterwards regardless of outcome. A ref that
+    doesn't resolve, or a `path` outside any git repo, exits 2 with the
+    reason on stderr. The report gets a top-level `"baseline": {"ref":
+    ..., "sha": ...}`; the summary and exit code count only the new
+    findings; `--format text` prints only the new findings plus the
+    baseline ref on the totals line. Since a fresh worktree has no
+    `.venv` of its own, the baseline's ty run is given `--python`
+    explicitly — the current run's resolved `ty-environment` Python
+    environment, unless you passed your own `--python` — and the report
+    names which one it used under `"baseline"`'s `"ty-python"` key.
+    `--skip` and `--extra-search-path` apply to both runs.
+  - **File-move artifact in the delta.** The baseline keys findings by
+    `(file, rule, message)`. A refactor that moves code from `old/x.py`
+    to `new/y.py` reports the entry at `old/x.py` as *gone* and the same
+    finding at `new/y.py` as *new* — net delta +1 even though the
+    codebase's lint posture is unchanged. Two responses: (a) accept the
+    +1 and document the move in the commit message; (b) commit and
+    refresh the baseline. Prefer (a) for one-off moves; (b) only when a
+    move is large enough to otherwise swamp the real new findings.
+- `uv run python-linters --version` — prints this package's version and
+  the bundled ruff/ty/pymodularity versions on one line.
+- `uv run python-linters reference ruff|ty` — prints this package's shipped
+  reference config for the given tool to stdout. The package never writes
+  it into your project — copying it into `ruff.toml`/`ty.toml` (or
+  `pyproject.toml`) stays with you.
+- `uv run python-linters check-config ruff|ty <path/to/config>` — compares
+  your copy against the pinned tool's current rule set: rules the tool
+  knows that your config omits (untriaged), and rules your config names
+  that the tool no longer knows (stale). The report names the version of
+  the tool it checked against on its first line.
+
+## Exit codes
+
+- `lint`: 0 clean, 1 findings, 2 any tool failure (named on stderr), a
+  usage error (e.g. `--skip` naming all 4 tools), or — with
+  `--baseline` — a ref that doesn't resolve or a path outside any git
+  repo.
+- `check-config`: 0 up to date, 1 untriaged or stale rules found, 2 tool
+  failure.

python_linters-0.2.3.dist-info/RECORD

@@ -0,0 +1,16 @@
+python_linters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_linters/__main__.py,sha256=Xkx-N0S-OWOvqBBgDA0HgCwrW324UrwBEQbR8PUayJI,158
+python_linters/baseline_report.py,sha256=IMDJ9kb8G1hVrN6FJi8tlS8qTD1CThyP5kLeWr6bbAI,7565
+python_linters/cli_commands.py,sha256=ZaLvKjGd8b5aZX7myTmXQHuq98EMrRaLVs77ScQTlgQ,5454
+python_linters/config_check.py,sha256=gFsI8KVBRkY_x7cREdRE3G51se_sfQAMAacTWR7pdxk,14687
+python_linters/lint_report.py,sha256=usr2__SlHcniIhxHrOfm1xOzT631O5NURnDGND9yqsY,17650
+python_linters/reference_files.py,sha256=pD0fGW-PJiV09LFIy9-hZKD7EVmHIUjkE3SfD-NeiI4,764
+python_linters/references/ruff.reference.toml,sha256=Q6kKaeekpeiGcVQoqPDdFfWA-jUij66s8q33EZWWZQ0,29668
+python_linters/references/ty.reference.toml,sha256=AKwhaBhs75QwbtrgqhuyoAYFTQX9Y7ns7TtwF8reQ4E,8244
+python_linters/text_report.py,sha256=L6NRS9tXUoUhEA1ECd94Nzr5S4VKyU8NRCtSRtVV0ik,1814
+python_linters/tool_errors.py,sha256=Fw3byFD0kk8QKJQg85weKB11_CRrnu2h_N2XQId6Abc,1572
+python_linters/tool_versions.py,sha256=9XASpuj1L0CB_0css6yxBuBMWaMCIyq3r6YRRxTvZmE,726
+python_linters-0.2.3.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
+python_linters-0.2.3.dist-info/entry_points.txt,sha256=2qemc7DiLCP7wVNw-8KENf-v5L62Jx40tHgVXC0s_FM,65
+python_linters-0.2.3.dist-info/METADATA,sha256=wCV0j0SXk8vbUBonKKKLXFWIWb1ySYB2VKuRM3woYNw,5524
+python_linters-0.2.3.dist-info/RECORD,,

{python_linters-0.2.1.dist-info → python_linters-0.2.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.13.6
+Generator: uv 0.13.8
 Root-Is-Purelib: true
 Tag: py3-none-any

python_linters-0.2.1.dist-info/METADATA

@@ -1,44 +0,0 @@
-Metadata-Version: 2.4
-Name: python-linters
-Version: 0.2.1
-Summary: Run ruff, ty and pymodularity on a Python project and print one JSON report grouped by rule.
-Author: Tilo Himmelsbach
-License-Expression: MIT
-Requires-Dist: ruff==0.17.3
-Requires-Dist: ty==0.0.90
-Requires-Dist: pymodularity==0.5.0
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# python-linters
-
-Run ruff, ty and pymodularity on a Python project and print one JSON report
-grouped by rule, for agents and CI to read.
-
-## Install
-
-As a dev dependency of the project you want to lint:
-
-```
-uv add --dev python-linters
-```
-
-## Commands
-
-- `uv run python-linters lint [path] [--out FILE]` — runs ruff, ty and
-  pymodularity (default path: `.`) and prints the merged JSON report to
-  stdout, or writes it to `FILE` with `--out`.
-- `uv run python-linters reference ruff|ty` — prints this package's shipped
-  reference config for the given tool to stdout. The package never writes
-  it into your project — copying it into `ruff.toml`/`ty.toml` (or
-  `pyproject.toml`) stays with you.
-- `uv run python-linters check-config ruff|ty <path/to/config>` — compares
-  your copy against the pinned tool's current rule set: rules the tool
-  knows that your config omits (untriaged), and rules your config names
-  that the tool no longer knows (stale).
-
-## Exit codes
-
-- `lint`: 0 clean, 1 findings, 2 any tool failure (named on stderr).
-- `check-config`: 0 up to date, 1 untriaged or stale rules found, 2 tool
-  failure.

python_linters-0.2.1.dist-info/RECORD

@@ -1,13 +0,0 @@
-python_linters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_linters/__main__.py,sha256=Xkx-N0S-OWOvqBBgDA0HgCwrW324UrwBEQbR8PUayJI,158
-python_linters/cli_commands.py,sha256=tVneEJJd6bgBrzunto3UJoEJHupwc5wNjMfTGwFCmN0,3122
-python_linters/config_check.py,sha256=gFsI8KVBRkY_x7cREdRE3G51se_sfQAMAacTWR7pdxk,14687
-python_linters/lint_report.py,sha256=5eCrWtZVEKi7Hulbw0VrkKbTnwDav2MuqEo8RmKCKSo,10623
-python_linters/reference_files.py,sha256=pD0fGW-PJiV09LFIy9-hZKD7EVmHIUjkE3SfD-NeiI4,764
-python_linters/references/ruff.reference.toml,sha256=J7uUpDhi6STS3yoUlyO1ZT2dgQLb9gJmFpFScKzupng,29058
-python_linters/references/ty.reference.toml,sha256=674u63jOImBHrY92lAa27ZcilevZj6GSqxWywp6kQTw,7677
-python_linters/tool_errors.py,sha256=Fw3byFD0kk8QKJQg85weKB11_CRrnu2h_N2XQId6Abc,1572
-python_linters-0.2.1.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
-python_linters-0.2.1.dist-info/entry_points.txt,sha256=2qemc7DiLCP7wVNw-8KENf-v5L62Jx40tHgVXC0s_FM,65
-python_linters-0.2.1.dist-info/METADATA,sha256=SwxLKHe6IGzYTOX3xETKwesEehJ8DUwiUI470ynXJR4,1497
-python_linters-0.2.1.dist-info/RECORD,,