python-linters 0.2.2__tar.gz → 0.2.3__tar.gz

python_linters-0.2.3/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,93 @@
+# 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.2 → python_linters-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-linters"
-version = "0.2.2"
+version = "0.2.3"
 description = "Run ruff, ty and pymodularity on a Python project and print one JSON report grouped by rule."
 readme = "README.md"
 license = "MIT"

{python_linters-0.2.2 → python_linters-0.2.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-linters"
-version = "0.2.2"
+version = "0.2.3"
 description = "Run ruff, ty and pymodularity on a Python project and print one JSON report grouped by rule."
 readme = "README.md"
 license = "MIT"

python_linters-0.2.3/src/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-0.2.2 → python_linters-0.2.3}/src/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-0.2.2 → python_linters-0.2.3}/src/python_linters/lint_report.py

@@ -5,6 +5,13 @@ 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},
@@ -41,6 +48,10 @@ 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
@@ -54,6 +65,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 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
@@ -64,6 +76,24 @@ _TY_SEVERITY_MAP = {"major": "error", "minor": "warning", "info": "info"}
 #  --> 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:
@@ -220,7 +250,49 @@ def run_ruff_format(project_path: Path) -> dict[str, FindingGroup]:
     return groups
 
 
-def run_ty(project_path: Path) -> dict[str, FindingGroup]:
+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`.
@@ -247,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)
 
@@ -287,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]:
@@ -333,20 +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),
-        ("ruff-format", run_ruff_format),
-        ("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)
 
@@ -354,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-0.2.3/src/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-0.2.3/src/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.2/PKG-INFO

@@ -1,44 +0,0 @@
-Metadata-Version: 2.4
-Name: python-linters
-Version: 0.2.2
-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]` — runs ruff, `ruff
-  format --check`, 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.2/README.md

@@ -1,32 +0,0 @@
-# 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, `ruff
-  format --check`, 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.