readability-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{readability_cli-0.4.0 → readability_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -37,10 +37,10 @@ You can run the tool directly without installing it using `uvx`:
 
 ```bash
 # Check and fix formatting for the current directory
-uvx --from git+https://github.com/owahltinez/readability.git readability check . --fix
+uvx --from readability-cli readability check . --fix
 
 # Get the Python style guide
-uvx --from git+https://github.com/owahltinez/readability.git readability guide python
+uvx --from readability-cli readability guide python
 ```
 
 ## Installation
@@ -49,7 +49,7 @@ Install it as a global tool with `uv`:
 
 ```bash
 # Install the readability tool
-uv tool install git+https://github.com/owahltinez/readability.git
+uv tool install readability-cli
 
 # Use it anywhere
 readability check .
@@ -128,10 +128,19 @@ readability guide python --remote
 # Save a style guide to a file
 readability guide cpp --output cpp-style.md
 
+# Print where the guide already lives, to search it without copying it
+readability guide python --path
+grep -n "Naming" "$(readability guide python --path)"
+
 # Synchronize all supported style guides to the local cache
 readability sync
 ```
 
+A guide can exceed 100 KB, so `--path` is the cheap way to consult one: the
+file is already on disk, and searching it beats reading it whole or writing
+out a second copy. It is also what a coding agent should use, rather than
+redirecting the guide into a repository.
+
 ### Supported Languages
 
 Use `readability languages` to see a full list of supported languages and
@@ -190,3 +199,17 @@ Check code style with `ruff`:
 uv run ruff check .
 uv run ruff format .
 ```
+
+### Releasing
+
+Releases are published to PyPI as
+[`readability-cli`](https://pypi.org/project/readability-cli/) via trusted
+publishing: pushing a `v*` tag triggers the `publish.yml` GitHub Actions
+workflow, which builds the package with `uv build` and uploads it.
+
+```bash
+# 1. Bump the version in pyproject.toml, commit, and push
+# 2. Tag the release and push the tag
+git tag v0.4.1
+git push origin v0.4.1
+```

{readability_cli-0.4.0 → readability_cli-0.6.0}/README.md

@@ -23,10 +23,10 @@ You can run the tool directly without installing it using `uvx`:
 
 ```bash
 # Check and fix formatting for the current directory
-uvx --from git+https://github.com/owahltinez/readability.git readability check . --fix
+uvx --from readability-cli readability check . --fix
 
 # Get the Python style guide
-uvx --from git+https://github.com/owahltinez/readability.git readability guide python
+uvx --from readability-cli readability guide python
 ```
 
 ## Installation
@@ -35,7 +35,7 @@ Install it as a global tool with `uv`:
 
 ```bash
 # Install the readability tool
-uv tool install git+https://github.com/owahltinez/readability.git
+uv tool install readability-cli
 
 # Use it anywhere
 readability check .
@@ -114,10 +114,19 @@ readability guide python --remote
 # Save a style guide to a file
 readability guide cpp --output cpp-style.md
 
+# Print where the guide already lives, to search it without copying it
+readability guide python --path
+grep -n "Naming" "$(readability guide python --path)"
+
 # Synchronize all supported style guides to the local cache
 readability sync
 ```
 
+A guide can exceed 100 KB, so `--path` is the cheap way to consult one: the
+file is already on disk, and searching it beats reading it whole or writing
+out a second copy. It is also what a coding agent should use, rather than
+redirecting the guide into a repository.
+
 ### Supported Languages
 
 Use `readability languages` to see a full list of supported languages and
@@ -176,3 +185,17 @@ Check code style with `ruff`:
 uv run ruff check .
 uv run ruff format .
 ```
+
+### Releasing
+
+Releases are published to PyPI as
+[`readability-cli`](https://pypi.org/project/readability-cli/) via trusted
+publishing: pushing a `v*` tag triggers the `publish.yml` GitHub Actions
+workflow, which builds the package with `uv build` and uploads it.
+
+```bash
+# 1. Bump the version in pyproject.toml, commit, and push
+# 2. Tag the release and push the tag
+git tag v0.4.1
+git push origin v0.4.1
+```

{readability_cli-0.4.0 → readability_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.4.0"
+version = "0.6.0"
 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.4.0 → readability_cli-0.6.0}/readability.py

@@ -253,6 +253,38 @@ def cli(ctx: click.Context, verbose: bool) -> None:
         logger.setLevel(logging.DEBUG)
 
 
+def _echo_guide_path(language: str) -> None:
+    """Print the local path of a language's style guide.
+
+    Args:
+        language: The language whose guide is being located.
+
+    Raises:
+        SystemExit: If the language is unsupported or its guide is absent.
+    """
+    filename = LANGUAGE_MAP.get(language.lower())
+    if not filename:
+        click.echo(
+            f"Error: Language '{language}' is not supported. Supported "
+            f"languages: {', '.join(sorted(LANGUAGE_MAP.keys()))}",
+            err=True,
+        )
+        sys.exit(1)
+
+    local_path = get_local_path(filename)
+    if not os.path.exists(local_path):
+        # Naming a file that is not there would send the caller to read
+        # nothing; fetching it is what `sync` is for.
+        click.echo(
+            f"Error: No local guide for '{language}' at {local_path}. "
+            "Run 'readability sync' to fetch it.",
+            err=True,
+        )
+        sys.exit(1)
+
+    click.echo(local_path)
+
+
 @cli.command()
 @click.argument("language")
 @click.option(
@@ -264,9 +296,20 @@ def cli(ctx: click.Context, verbose: bool) -> None:
 @click.option(
     "--remote", "-r", is_flag=True, help="Force fetching from the web."
 )
+@click.option(
+    "--path",
+    "-p",
+    "show_path",
+    is_flag=True,
+    help="Print where the guide is stored instead of its contents.",
+)
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging.")
 def guide(
-    language: str, output: Optional[str], remote: bool, verbose: bool
+    language: str,
+    output: Optional[str],
+    remote: bool,
+    show_path: bool,
+    verbose: bool,
 ) -> None:
     """Fetch the style guide for a specific LANGUAGE."""
     if verbose:
@@ -274,6 +317,13 @@ def guide(
 
     logger.info("Processing style guide for: %s", language)
 
+    # A guide runs to hundreds of kilobytes, so a caller that wants a few
+    # rules is better served searching the copy already on disk than
+    # reading the whole thing or writing out a second one.
+    if show_path:
+        _echo_guide_path(language)
+        return
+
     try:
         # Fetch and process the style guide
         markdown_content = get_guide(language, remote=remote)
@@ -362,32 +412,47 @@ def languages() -> None:
 )
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging.")
 def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
-    """Run relevant formatters and linters for given paths."""
+    """Run relevant formatters and linters for given paths.
+
+    Exits with a non-zero status code if any tool reports findings, so the
+    command can gate scripts and CI.
+    """
     if verbose:
         logger.setLevel(logging.DEBUG)
 
     # Resolve project root once for trigger file checking
     project_root = Path.cwd()
 
-    # Process each provided path independently
+    # Process each provided path independently, tracking findings across
+    # all of them so the exit code reflects the overall result
+    found_issues = False
     for path_str in paths:
-        _check_path(Path(path_str), project_root, fix=fix)
+        found_issues |= _check_path(Path(path_str), project_root, fix=fix)
 
+    if found_issues:
+        sys.exit(1)
 
-def _check_path(path: Path, project_root: Path, fix: bool = False) -> None:
+
+def _check_path(path: Path, project_root: Path, fix: bool = False) -> bool:
     """Apply relevant tools to a single path.
 
     Args:
         path: The path (file or directory) to check.
         project_root: The root of the project for trigger file discovery.
         fix: Whether to apply automatic fixes.
+
+    Returns:
+        True if any tool reported findings, False otherwise.
     """
     logger.info("Checking path: %s", path)
 
     # Iterate through all supported tool definitions
+    found_issues = False
     for tool in _get_tool_definitions(path, project_root):
         if _should_run_tool(tool, path, project_root):
-            _run_tool(tool["name"], tool, fix=fix)
+            found_issues |= _run_tool(tool["name"], tool, fix=fix)
+
+    return found_issues
 
 
 def _should_run_tool(
@@ -642,13 +707,16 @@ def _run_tool(
     tool_name: str,
     tool_config: dict[str, Any],
     fix: bool = False,
-) -> None:
+) -> bool:
     """Orchestrate the execution of a specific formatting or linting tool.
 
     Args:
         tool_name: The name of the tool to run.
         tool_config: The tool configuration dictionary.
         fix: Whether to apply automatic fixes.
+
+    Returns:
+        True if the tool reported findings, False otherwise.
     """
     # Identify the primary command to check for executable availability
     cmd = (
@@ -658,16 +726,17 @@ def _run_tool(
         or tool_config.get("check_format")
     )
     if not cmd:
-        return
+        return False
 
     executable = str(cmd[0])
     if not shutil.which(executable):
         logger.debug(
             "Tool %s (%s) not found in PATH, skipping.", tool_name, executable
         )
-        return
+        return False
 
     logger.info("Running %s...", tool_name)
+    found_issues = False
     try:
         if fix:
             # 1. Run formatters (if available) - these are expected to
@@ -691,6 +760,7 @@ def _run_tool(
             if result.returncode != 0 or (
                 tool_name == "go fmt" and result.stdout.strip()
             ):
+                found_issues = True
                 click.echo(
                     f"--- {tool_name} formatting findings ---\n"
                     f"{result.stdout}\n{result.stderr}"
@@ -707,6 +777,7 @@ def _run_tool(
                 timeout=DEFAULT_TIMEOUT,
             )
             if result.returncode != 0:
+                found_issues = True
                 click.echo(
                     f"--- {tool_name} findings ---\n"
                     f"{result.stdout}\n{result.stderr}"
@@ -721,6 +792,8 @@ def _run_tool(
     except (subprocess.SubprocessError, OSError) as e:
         logger.warning("Unexpected error while running %s: %s", tool_name, e)
 
+    return found_issues
+
 
 def _execute_tool_command(cmd: list[str]) -> None:
     """Execute a tool command, raising if it exits with a non-zero code.

{readability_cli-0.4.0 → readability_cli-0.6.0}/test_readability.py

@@ -151,6 +151,52 @@ def test_cli_output_file(mock_guide: MagicMock, tmp_path: Path) -> None:
     assert output_file.read_text() == "# Style Guide"
 
 
+def test_cli_path_prints_the_location(tmp_path: Path, monkeypatch) -> None:
+    """Tests that --path reports where the guide already lives on disk.
+
+    Guides ship with the package, so a caller wanting to search one needs
+    its location, not another copy of its contents.
+    """
+    monkeypatch.setenv("READABILITY_CACHE", str(tmp_path))
+    (tmp_path / "pyguide.md").write_text("# Style Guide")
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["guide", "python", "--path"])
+
+    assert result.exit_code == 0
+    assert result.output.strip() == str(tmp_path / "pyguide.md")
+    assert "# Style Guide" not in result.output
+
+
+def test_cli_path_reports_a_guide_not_yet_fetched(
+    tmp_path: Path, monkeypatch
+) -> None:
+    """Tests that a missing local guide fails instead of naming a phantom.
+
+    Printing a path to a file that is not there would send the caller to
+    read nothing at all.
+    """
+    monkeypatch.setenv("READABILITY_CACHE", str(tmp_path))
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["guide", "python", "--path"])
+
+    assert result.exit_code == 1
+    assert "sync" in result.output
+
+
+def test_cli_path_rejects_an_unsupported_language(
+    tmp_path: Path, monkeypatch
+) -> None:
+    """Tests that --path validates the language like the default path does."""
+    monkeypatch.setenv("READABILITY_CACHE", str(tmp_path))
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["guide", "nonexistent", "--path"])
+
+    assert result.exit_code == 1
+
+
 @patch("readability.get_guide")
 def test_cli_verbose(mock_guide: MagicMock) -> None:
     """Tests CLI with verbose flag.
@@ -559,3 +605,107 @@ def test_bundled_default_configs_are_valid(tmp_path: Path) -> None:
     ruff_config = tomllib.loads(_bundled_config("ruff").read_text())
     assert ruff_config["line-length"] == 80
     assert ruff_config["lint"]["pydocstyle"]["convention"] == "google"
+
+
+@patch("shutil.which")
+@patch("subprocess.run")
+def test_check_command_exits_nonzero_on_format_findings(
+    mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path
+) -> None:
+    """Tests that formatting findings produce a non-zero exit code.
+
+    Args:
+        mock_run: The mocked subprocess.run function.
+        mock_which: The mocked shutil.which function.
+        tmp_path: The temporary directory fixture.
+    """
+    mock_which.side_effect = lambda x: x if x == "ruff" else None
+
+    # Only `ruff format --check` reports findings
+    def run_side_effect(cmd, **kwargs):
+        if "format" in cmd:
+            return MagicMock(
+                returncode=1, stdout="Would reformat: script.py", stderr=""
+            )
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    mock_run.side_effect = run_side_effect
+
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("pyproject.toml").touch()
+        Path("script.py").touch()
+
+        result = runner.invoke(cli, ["check", "script.py"])
+
+    assert "formatting findings" in result.output
+    assert result.exit_code == 1
+
+
+@patch("shutil.which")
+@patch("subprocess.run")
+def test_check_command_exits_nonzero_on_check_findings(
+    mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path
+) -> None:
+    """Tests that linter findings produce a non-zero exit code.
+
+    Args:
+        mock_run: The mocked subprocess.run function.
+        mock_which: The mocked shutil.which function.
+        tmp_path: The temporary directory fixture.
+    """
+    mock_which.side_effect = lambda x: x if x == "ruff" else None
+
+    # Only `ruff check` reports findings
+    def run_side_effect(cmd, **kwargs):
+        if "check" in cmd and "format" not in cmd:
+            return MagicMock(
+                returncode=1, stdout="E501 line too long", stderr=""
+            )
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    mock_run.side_effect = run_side_effect
+
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("pyproject.toml").touch()
+        Path("script.py").touch()
+
+        result = runner.invoke(cli, ["check", "script.py"])
+
+    assert "findings" in result.output
+    assert result.exit_code == 1
+
+
+@patch("shutil.which")
+@patch("subprocess.run")
+def test_check_command_fix_exits_nonzero_on_remaining_findings(
+    mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path
+) -> None:
+    """Tests that findings remaining after --fix produce a non-zero exit.
+
+    Args:
+        mock_run: The mocked subprocess.run function.
+        mock_which: The mocked shutil.which function.
+        tmp_path: The temporary directory fixture.
+    """
+    mock_which.side_effect = lambda x: x if x == "ruff" else None
+
+    # Fixers succeed, but the check step still reports findings
+    def run_side_effect(cmd, **kwargs):
+        if "check" in cmd and "--fix" not in cmd:
+            return MagicMock(
+                returncode=1, stdout="E501 line too long", stderr=""
+            )
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    mock_run.side_effect = run_side_effect
+
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("pyproject.toml").touch()
+        Path("script.py").touch()
+
+        result = runner.invoke(cli, ["check", "--fix", "script.py"])
+
+    assert result.exit_code == 1

{readability_cli-0.4.0 → readability_cli-0.6.0}/uv.lock

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