readability-cli 0.8.0__tar.gz → 0.8.2__tar.gz

{readability_cli-0.8.0 → readability_cli-0.8.2}/.github/workflows/ci.yml

@@ -29,3 +29,12 @@ jobs:
 
       - name: Run tests
         run: uv run pytest
+
+      # Runs the tool against itself, which is the only place tool
+      # resolution is exercised for real: the unit tests reach it with
+      # shutil.which mocked, so they cannot tell whether a resolved command
+      # actually starts. ruff comes from the synced environment and pyrefly
+      # is not a dependency at all, so this covers both the PATH branch and
+      # the uvx runner, on a machine that has neither installed.
+      - name: Check this repository with the tool itself
+        run: uv run readability check .

{readability_cli-0.8.0 → readability_cli-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.8.0
+Version: 0.8.2
 Summary: A CLI to lint, format, and type-check code with Google-style defaults, and pull Google style guides in markdown format.
 Project-URL: Homepage, https://github.com/owahltinez/readability
 Project-URL: Repository, https://github.com/owahltinez/readability
@@ -147,6 +147,28 @@ the state a container image is usually in.
 `check` exits non-zero on findings and on having verified nothing, so it can
 gate CI without a clean exit ever meaning "the tools were absent".
 
+### Python API
+
+Use `check_paths` to run the same checks without the command's status messages
+or exit-code decisions:
+
+```python
+from pathlib import Path
+
+from readability import check_paths
+
+report = check_paths(["src", Path("tests")], project_root=Path.cwd())
+if report.findings or report.failed or not report.ran:
+    handle_failed_check(report)
+```
+
+The returned `CheckReport` records only whether findings occurred and which
+tools ran, were skipped, or failed. Detailed tool findings are still written
+as each tool runs. Every path is validated before any tool runs, and a missing
+one raises `FileNotFoundError` rather than being misreported as a finding.
+Relative paths remain relative to the process working directory;
+`project_root` controls configuration discovery only.
+
 ### Default Configurations
 
 For Ruff and Pyrefly, bundled defaults based on the

{readability_cli-0.8.0 → readability_cli-0.8.2}/README.md

@@ -133,6 +133,28 @@ the state a container image is usually in.
 `check` exits non-zero on findings and on having verified nothing, so it can
 gate CI without a clean exit ever meaning "the tools were absent".
 
+### Python API
+
+Use `check_paths` to run the same checks without the command's status messages
+or exit-code decisions:
+
+```python
+from pathlib import Path
+
+from readability import check_paths
+
+report = check_paths(["src", Path("tests")], project_root=Path.cwd())
+if report.findings or report.failed or not report.ran:
+    handle_failed_check(report)
+```
+
+The returned `CheckReport` records only whether findings occurred and which
+tools ran, were skipped, or failed. Detailed tool findings are still written
+as each tool runs. Every path is validated before any tool runs, and a missing
+one raises `FileNotFoundError` rather than being misreported as a finding.
+Relative paths remain relative to the process working directory;
+`project_root` controls configuration discovery only.
+
 ### Default Configurations
 
 For Ruff and Pyrefly, bundled defaults based on the

{readability_cli-0.8.0 → readability_cli-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.8.0"
+version = "0.8.2"
 description = "A CLI to lint, format, and type-check code with Google-style defaults, and pull Google style guides in markdown format."
 readme = "README.md"
 requires-python = ">=3.12"

{readability_cli-0.8.0 → readability_cli-0.8.2}/readability.py

@@ -1096,14 +1096,7 @@ def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
     if verbose:
         logger.setLevel(logging.DEBUG)
 
-    # Resolve project root once for trigger file checking
-    project_root = Path.cwd()
-
-    # Process each provided path independently, tracking findings across
-    # all of them so the exit code reflects the overall result
-    report = CheckReport()
-    for path_str in paths:
-        report.absorb(_check_path(Path(path_str), project_root, fix=fix))
+    report = check_paths(paths, fix=fix)
 
     # Coverage the caller does not know is missing reads as coverage
     if report.skipped:
@@ -1190,6 +1183,46 @@ class CheckReport:
         self.failed |= other.failed
 
 
+def check_paths(
+    paths: Sequence[str | Path],
+    project_root: Path | None = None,
+    fix: bool = False,
+) -> CheckReport:
+    """Run relevant checks for paths and aggregate what the tools did.
+
+    Detailed findings from the underlying tools are written as they are for
+    the command-line interface. This function does not print CLI status prose
+    or turn the report into a process exit code; callers decide how to handle
+    the result.
+
+    Args:
+        paths: Files or directories to check, as strings or paths. Relative
+            paths are interpreted from the current working directory.
+        project_root: Root used only to discover tool configuration. Defaults
+            to the current working directory; it does not rebase paths.
+        fix: Whether to apply automatic fixes.
+
+    Returns:
+        A report aggregated across all provided paths.
+
+    Raises:
+        FileNotFoundError: If any requested path does not exist. Every path is
+            validated before any tools run.
+    """
+    root = Path.cwd() if project_root is None else project_root
+    requested_paths = [Path(path) for path in paths]
+    missing_path = next(
+        (path for path in requested_paths if not path.exists()), None
+    )
+    if missing_path is not None:
+        raise FileNotFoundError(f"Path does not exist: {missing_path}")
+
+    report = CheckReport()
+    for path in requested_paths:
+        report.absorb(_check_path(path, root, fix=fix))
+    return report
+
+
 def _check_path(
     path: Path, project_root: Path, fix: bool = False
 ) -> CheckReport:

{readability_cli-0.8.0 → readability_cli-0.8.2}/test_readability.py

@@ -3,7 +3,7 @@ import os
 import subprocess
 import tomllib
 from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock, call, patch
 
 import click
 import pytest
@@ -13,11 +13,13 @@ from click.testing import CliRunner
 from readability import (
     LANGUAGE_MAP,
     TOOL_RUNNERS,
+    CheckReport,
     _bundled_config,
     _get_tool_definitions,
     _has_project_config,
     _iter_heading_lines,
     _unique_reference,
+    check_paths,
     cli,
     convert_to_markdown,
     extract_section,
@@ -518,6 +520,134 @@ def test_bundled_default_configs_are_valid(tmp_path: Path) -> None:
     assert ruff_config["lint"]["pydocstyle"]["convention"] == "google"
 
 
+@patch("readability._check_path")
+def test_check_paths_aggregates_str_and_path_inputs(
+    mock_check_path: MagicMock,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The public API folds each per-path result into one limited report."""
+    project_root = tmp_path / "project"
+    project_root.mkdir()
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "example.py").touch()
+    (tmp_path / "README.md").touch()
+    monkeypatch.chdir(tmp_path)
+    mock_check_path.side_effect = [
+        CheckReport(ran={"ruff"}, skipped={"pyrefly"}),
+        CheckReport(
+            findings=True,
+            ran={"prettier"},
+            failed={"biome"},
+        ),
+    ]
+
+    report = check_paths(
+        ["src/example.py", Path("README.md")],
+        project_root=project_root,
+        fix=True,
+    )
+
+    assert report == CheckReport(
+        findings=True,
+        ran={"ruff", "prettier"},
+        skipped={"pyrefly"},
+        failed={"biome"},
+    )
+    assert mock_check_path.call_args_list == [
+        call(Path("src/example.py"), project_root, fix=True),
+        call(Path("README.md"), project_root, fix=True),
+    ]
+
+
+@patch("readability._check_path", return_value=CheckReport(ran={"ruff"}))
+def test_check_paths_defaults_project_root_to_cwd(
+    mock_check_path: MagicMock,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The public API discovers configuration from the caller's directory."""
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "example.py").touch()
+
+    check_paths([Path("example.py")])
+
+    mock_check_path.assert_called_once_with(
+        Path("example.py"), tmp_path, fix=False
+    )
+
+
+@patch("readability._check_path")
+def test_check_paths_with_no_paths_reports_that_nothing_ran(
+    mock_check_path: MagicMock,
+) -> None:
+    """An empty request must not look like a verified clean result."""
+    report = check_paths([])
+
+    assert report == CheckReport()
+    assert not report.ran
+    mock_check_path.assert_not_called()
+
+
+@patch("readability._check_path")
+def test_check_paths_rejects_missing_paths_before_dispatch(
+    mock_check_path: MagicMock,
+    tmp_path: Path,
+) -> None:
+    """A missing path prevents partial checks and fixes on earlier paths."""
+    existing = tmp_path / "exists.py"
+    missing = tmp_path / "missing.py"
+    existing.touch()
+
+    with pytest.raises(FileNotFoundError) as excinfo:
+        check_paths([existing, missing], project_root=tmp_path, fix=True)
+
+    assert str(missing) in str(excinfo.value)
+    mock_check_path.assert_not_called()
+
+
+@patch(
+    "readability._check_path",
+    return_value=CheckReport(
+        findings=True,
+        skipped={"pyrefly"},
+        failed={"ruff"},
+    ),
+)
+def test_check_paths_returns_report_without_cli_status_prose(
+    mock_check_path: MagicMock,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+) -> None:
+    """Library callers receive report states without CLI policy or summaries."""
+    path = tmp_path / "example.py"
+    path.touch()
+
+    report = check_paths([path])
+
+    assert report.findings is True
+    assert report.skipped == {"pyrefly"}
+    assert report.failed == {"ruff"}
+    assert capsys.readouterr() == ("", "")
+    mock_check_path.assert_called_once()
+
+
+@patch("readability.check_paths", return_value=CheckReport(ran={"ruff"}))
+def test_check_command_delegates_to_public_api(
+    mock_check_paths: MagicMock, tmp_path: Path
+) -> None:
+    """The CLI keeps its output policy while delegating check execution."""
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("script.py").touch()
+        result = runner.invoke(cli, ["check", "script.py"])
+
+    mock_check_paths.assert_called_once_with(("script.py",), fix=False)
+    assert result.exit_code == 0
+    assert result.stdout == ""
+    assert result.stderr == "No findings in 1 path(s) (ruff).\n"
+
+
 @patch("shutil.which")
 @patch("subprocess.run")
 def test_check_command_exits_nonzero_on_format_findings(

{readability_cli-0.8.0 → readability_cli-0.8.2}/uv.lock

@@ -194,7 +194,7 @@ wheels = [
 
 [[package]]
 name = "readability-cli"
-version = "0.8.0"
+version = "0.8.2"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },