readability-cli 0.10.0__tar.gz → 0.10.2__tar.gz

{readability_cli-0.10.0 → readability_cli-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.10.0
+Version: 0.10.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
@@ -90,8 +90,16 @@ readability check src/ tests/ main.py
 
 # Automatically fix and format files
 readability check . --fix
+
+# Also apply fixes that may change behavior (implies --fix)
+readability check . --unsafe
 ```
 
+Fixes that may change a program's behavior or drop its comments are opt-in
+through `--unsafe`, which every tool applies under its own name: Ruff's
+`--unsafe-fixes` and Biome's `--unsafe`. Tools drawing no such distinction,
+such as gofmt, are unaffected by it.
+
 ### Supported Formats
 
 | Formats                                                          | Owners                                  | Project configuration                 |
@@ -180,8 +188,9 @@ caller happened to be standing in.
 
 Ruff and Pyrefly defaults follow the
 [Google Python style guide](https://google.github.io/styleguide/pyguide.html):
-80-column lines, Google docstrings, import ordering, and full type checking. The
-Biome default applies the 80-column lines and two-space indentation of the
+80-column lines, Google docstrings, one import per line sorted as isort's
+`google` profile does, and full type checking. The Biome default applies the
+80-column lines and two-space indentation of the
 [Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html)
 and enables Biome's recommended lint rules. Project `biome.json` and
 `biome.jsonc` files replace those bundled defaults for Biome-owned formats.

{readability_cli-0.10.0 → readability_cli-0.10.2}/README.md

@@ -76,8 +76,16 @@ readability check src/ tests/ main.py
 
 # Automatically fix and format files
 readability check . --fix
+
+# Also apply fixes that may change behavior (implies --fix)
+readability check . --unsafe
 ```
 
+Fixes that may change a program's behavior or drop its comments are opt-in
+through `--unsafe`, which every tool applies under its own name: Ruff's
+`--unsafe-fixes` and Biome's `--unsafe`. Tools drawing no such distinction,
+such as gofmt, are unaffected by it.
+
 ### Supported Formats
 
 | Formats                                                          | Owners                                  | Project configuration                 |
@@ -166,8 +174,9 @@ caller happened to be standing in.
 
 Ruff and Pyrefly defaults follow the
 [Google Python style guide](https://google.github.io/styleguide/pyguide.html):
-80-column lines, Google docstrings, import ordering, and full type checking. The
-Biome default applies the 80-column lines and two-space indentation of the
+80-column lines, Google docstrings, one import per line sorted as isort's
+`google` profile does, and full type checking. The Biome default applies the
+80-column lines and two-space indentation of the
 [Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html)
 and enables Biome's recommended lint rules. Project `biome.json` and
 `biome.jsonc` files replace those bundled defaults for Biome-owned formats.

{readability_cli-0.10.0 → readability_cli-0.10.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.10.0"
+version = "0.10.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"
@@ -47,6 +47,12 @@ ignore = ["PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR2004"]
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
+[tool.ruff.lint.isort]
+force-single-line = true
+force-sort-within-sections = true
+single-line-exclusions = ["typing"]
+order-by-type = false
+
 [tool.ruff.lint.per-file-ignores]
 "test_*.py" = ["D"]
 "*_test.py" = ["D"]

{readability_cli-0.10.0 → readability_cli-0.10.2}/readability/checking.py

@@ -1,21 +1,19 @@
 """Run readability checks and report their coverage."""
 
+from collections.abc import Sequence
 import dataclasses
 import logging
-import subprocess
-from collections.abc import Sequence
 from pathlib import Path
+import subprocess
 
 import click
 
-from readability.tools import (
-    ToolPlan,
-    _command_batches,
-    _get_tool_definitions,
-    _repository_root,
-    _should_run_tool,
-    _tool_is_installed,
-)
+from readability.tools import _command_batches
+from readability.tools import _get_tool_definitions
+from readability.tools import _repository_root
+from readability.tools import _should_run_tool
+from readability.tools import _tool_is_installed
+from readability.tools import ToolPlan
 
 logger = logging.getLogger("readability")
 DEFAULT_TIMEOUT = 60
@@ -64,6 +62,7 @@ def check_paths(
     paths: Sequence[str | Path],
     project_root: Path | None = None,
     fix: bool = False,
+    unsafe: bool = False,
 ) -> CheckReport:
     """Run relevant checks for paths and aggregate what the tools did.
 
@@ -80,6 +79,8 @@ def check_paths(
             and ignore files. Defaults to the repository the process is in.
             It does not rebase paths.
         fix: Whether to apply automatic fixes.
+        unsafe: Whether those fixes may change behavior or drop comments.
+            Tools that draw no such distinction are unaffected.
 
     Returns:
         A report aggregated across all provided paths.
@@ -102,7 +103,7 @@ def check_paths(
 
     report = CheckReport()
     for path in requested_paths:
-        path_report = _check_path(path, root, boundary, fix=fix)
+        path_report = _check_path(path, root, boundary, fix=fix, unsafe=unsafe)
         if not path_report.ran:
             path_report.unverified_paths.append(path)
         report.absorb(path_report)
@@ -114,6 +115,7 @@ def _check_path(
     project_root: Path,
     boundary: Path | None = None,
     fix: bool = False,
+    unsafe: bool = False,
 ) -> CheckReport:
     """Apply relevant tools to a single path.
 
@@ -123,6 +125,7 @@ def _check_path(
         boundary: Outermost directory config discovery may consider, or
             None to bound it by the path's own repository.
         fix: Whether to apply automatic fixes.
+        unsafe: Whether those fixes may change behavior or drop comments.
 
     Returns:
         What the tools applicable to this path did.
@@ -143,7 +146,7 @@ def _check_path(
             report.skipped.add(tool.name)
             continue
 
-        report.absorb(_run_tool(tool, fix=fix))
+        report.absorb(_run_tool(tool, fix=fix, unsafe=unsafe))
 
     return report
 
@@ -151,12 +154,14 @@ def _check_path(
 def _run_tool(
     tool: ToolPlan,
     fix: bool = False,
+    unsafe: bool = False,
 ) -> CheckReport:
     """Orchestrate the execution of a specific formatting or linting tool.
 
     Args:
         tool: The executable plan to run.
         fix: Whether to apply automatic fixes.
+        unsafe: Whether those fixes may change behavior or drop comments.
 
     Returns:
         What the tool did: whether it reported findings, and whether it
@@ -170,9 +175,11 @@ def _run_tool(
     target_count = len(tool.targets or ())
     try:
         if fix:
+            # A tool with no unsafe mode still fixes what it safely can
+            unsafe_fix = tool.unsafe_fix if unsafe else ()
+            phases = (("format", tool.format), ("fix", unsafe_fix or tool.fix))
             # Leftovers exit non-zero, which is a finding rather than a failure
-            for phase in ("format", "fix"):
-                configured_command = getattr(tool, phase)
+            for phase, configured_command in phases:
                 if configured_command:
                     commands = _command_batches(
                         configured_command, target_count

{readability_cli-0.10.0 → readability_cli-0.10.2}/readability/cli.py

@@ -1,21 +1,20 @@
 """Command-line interface for readability."""
 
+from collections.abc import Sequence
 import logging
 import os
 import sys
-from collections.abc import Sequence
 
 import click
 
 from readability.checking import check_paths
-from readability.guide import (
-    LANGUAGE_MAP,
-    get_guide,
-    get_guides_dir,
-    get_local_path,
-    refresh_guide,
-)
-from readability.outline import _echo_outline, _select_section
+from readability.guide import get_guide
+from readability.guide import get_guides_dir
+from readability.guide import get_local_path
+from readability.guide import LANGUAGE_MAP
+from readability.guide import refresh_guide
+from readability.outline import _echo_outline
+from readability.outline import _select_section
 
 logger = logging.getLogger("readability")
 
@@ -168,8 +167,13 @@ def _echo_languages() -> None:
 @click.option(
     "--fix", is_flag=True, help="Automatically fix issues if possible."
 )
+@click.option(
+    "--unsafe",
+    is_flag=True,
+    help="Also apply fixes that may change behavior. Implies --fix.",
+)
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging.")
-def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
+def check(paths: Sequence[str], fix: bool, unsafe: bool, verbose: bool) -> None:
     """Run relevant formatters and linters for given paths.
 
     Exits with a non-zero status code if any tool reports findings, so the
@@ -178,7 +182,8 @@ def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
     if verbose:
         logger.setLevel(logging.DEBUG)
 
-    report = check_paths(paths, fix=fix)
+    # Unsafe fixes are still fixes, so asking for them is asking to fix
+    report = check_paths(paths, fix=fix or unsafe, unsafe=unsafe)
 
     # Coverage the caller does not know is missing reads as coverage
     if report.skipped:

{readability_cli-0.10.0 → readability_cli-0.10.2}/readability/configs/ruff.toml

@@ -14,6 +14,14 @@ ignore = ["PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR2004"]
 [lint.pydocstyle]
 convention = "google"
 
+[lint.isort]
+# Mirrors isort's google profile; its lexicographical and group-by-package
+# options have no ruff equivalent
+force-single-line = true
+force-sort-within-sections = true
+single-line-exclusions = ["typing"]
+order-by-type = false
+
 [lint.per-file-ignores]
 # Docstring requirements are noise in test files
 "test_*.py" = ["D"]

{readability_cli-0.10.0 → readability_cli-0.10.2}/readability/guide.py

@@ -1,14 +1,15 @@
 """Fetch and cache Google style guides."""
 
+from importlib.resources import files
 import logging
 import os
 import warnings
-from importlib.resources import files
 
+from bs4 import BeautifulSoup
+from bs4 import XMLParsedAsHTMLWarning
 import click
-import requests
-from bs4 import BeautifulSoup, XMLParsedAsHTMLWarning
 from markdownify import markdownify as md
+import requests
 
 warnings.filterwarnings("ignore", category=XMLParsedAsHTMLWarning)
 
@@ -55,10 +56,7 @@ LANGUAGE_MAP = {
 
 BASE_URL = "https://google.github.io/styleguide/"
 
-# Style guides are dense with snake_case and dunder identifiers, and escaping
-# their underscores leaves 'from \_\_future\_\_ import' in the text a caller
-# greps or reads. CommonMark would render a bare '__future__' as emphasis, but
-# these guides are consumed as plain text, where fidelity matters more.
+# Escaping underscores would leave 'from \_\_future\_\_ import' in the text
 MARKDOWNIFY_OPTIONS = {"heading_style": "ATX", "escape_underscores": False}
 
 

{readability_cli-0.10.0 → readability_cli-0.10.2}/readability/outline.py

@@ -1,31 +1,27 @@
 """Parse, search, and render style-guide outlines."""
 
+from collections.abc import Iterator
+from collections.abc import Sequence
+from dataclasses import dataclass
 import re
 import sys
-from collections.abc import Iterator, Sequence
-from dataclasses import dataclass
 from typing import Any
 
 import click
 
-# A fence opens or closes a code block; anything inside is sample code, not
-# document structure. Guides for `#`-commented languages (shell, Python) would
-# otherwise report hundreds of code comments as headings.
+# Inside a fence is sample code, where a '#' comment is not a heading
 FENCE_PATTERN = re.compile(r"^\s{0,3}(?:```|~~~)")
 
-# Closing hashes are optional in ATX headings and must be space-separated, so
-# a title such as 'C#' keeps its trailing character.
+# Closing hashes are space-separated, so a title like 'C#' keeps its own
 HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.*?)(?:\s+#+)?\s*$")
 
-# A section number the document itself prints, e.g. '2.2' in '2.2 Imports'.
+# A number the document prints itself, e.g. '2.2' in '2.2 Imports'
 DOCUMENT_NUMBER_PATTERN = re.compile(r"^(\d+(?:\.\d+)*)\.?\s+(.+)$")
 
-# Guides put a heading's link targets on the lines above it, which would
-# otherwise trail the end of the preceding section.
+# Link targets sit above their heading, not at the end of the one before
 ANCHOR_PATTERN = re.compile(r'^<a id="[^"]*"></a>$')
 
-# The separator in a scoped reference such as 'Imports > Decision'. Spaces on
-# both sides are required so that a heading like '`Array<T>` Type' stays whole.
+# Scoped reference separator; spaces required so '`Array<T>` Type' stays whole
 PATH_SEPARATOR_PATTERN = re.compile(r"\s+>\s+")
 
 
@@ -148,8 +144,7 @@ def parse_headings(content: str) -> list[Heading]:
     if not raw:
         return []
 
-    # Only three of the shipped guides number their headings. A dotted number
-    # ('2.2') is the reliable signal; a bare leading digit is not.
+    # A dotted number is the reliable signal; a bare leading digit is not
     document_numbers = [
         match.group(1)
         for _, _, text in raw
@@ -157,8 +152,7 @@ def parse_headings(content: str) -> list[Heading]:
     ]
     numbered = any("." in number for number in document_numbers)
 
-    # A lone top-level heading is the document title: it roots the tree rather
-    # than being the first section, so numbering starts with its children.
+    # A lone top-level heading is the title, so numbering starts below it
     top_level = min(level for _, level, _ in raw)
     top_level_lines = [line for line, level, _ in raw if level == top_level]
     title_line = top_level_lines[0] if len(top_level_lines) == 1 else None
@@ -169,12 +163,7 @@ def parse_headings(content: str) -> list[Heading]:
         index = "" if line == title_line else _next_index(open_headings, level)
         number, title = _split_document_number(text, numbered)
 
-        # A guide that numbers its own sections is the authority on what they
-        # are called, so its numbers address them. A positional index would
-        # drift wherever the guide skips one — pyguide has no 2.15 at all,
-        # and calling its 2.16 by that name would cite a section that does
-        # not exist. The tree still advances above, so headings the guide
-        # leaves unnumbered keep a positional index to be reachable by.
+        # A guide's own numbers address its sections; an index would drift
         if number:
             index = number
         headings.append(
@@ -203,10 +192,7 @@ def _slugify(text: str) -> str:
     return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
 
 
-# Sections this long are worth warning about before one is fetched. Measured
-# over the shipped corpus, it marks the 4% that are expensive while leaving
-# the rest unannotated: a size on every line would read '0' on 59% of them,
-# which is noise in the one output whose job is to be scanned quickly.
+# Marks the expensive 4% of the corpus; a size on every line would be noise
 LARGE_SECTION_WORDS = 1200
 
 
@@ -263,8 +249,7 @@ def format_outline(headings: Sequence[Heading], content: str = "") -> str:
             section = extract_section(content, headings, position)
             size = _format_size(len(section.split()))
 
-        # The index already carries the guide's own number where it has one,
-        # so printing the heading verbatim would show it twice.
+        # The index already carries the guide's number where it has one
         lines.append(f"{indent}{prefix}{heading.title}{size}")
 
     return "\n".join(lines)
@@ -281,8 +266,7 @@ def _matches_component(heading: Heading, component: str, exact: bool) -> bool:
     Returns:
         True if the component identifies the heading.
     """
-    # Numbers are only ever compared in full; a substring of a number would
-    # match unrelated sections.
+    # Numbers compare in full; a substring would match unrelated sections
     wanted = component.strip().rstrip(".")
     if wanted and wanted in {heading.index, heading.number}:
         return True
@@ -369,8 +353,7 @@ def find_headings(headings: Sequence[Heading], reference: str) -> list[int]:
     if not components:
         return []
 
-    # Prefer whole matches; fall back to substrings only when nothing matches
-    # in full, so 'Imports' does not also select 'Imports and Exports'.
+    # Whole matches first, so 'Imports' does not select 'Imports and Exports'
     for exact in (True, False):
         matches = [
             position
@@ -512,9 +495,7 @@ def find_mentions(
 
     lines = content.splitlines()
 
-    # Only an indexed heading can be offered. The document title has no index
-    # because it is the whole guide rather than a section within it, so
-    # crediting the preamble to it would suggest reading everything.
+    # The title has no index, so crediting it would suggest reading everything
     sections = [
         (position, _section_bounds(lines, headings, position))
         for position in range(len(headings))
@@ -526,10 +507,7 @@ def find_mentions(
         if needle not in line.lower():
             continue
 
-        # Bounds nest, so the last section still covering the line is the
-        # innermost one that prints it. A section sheds the anchors of the
-        # heading below it, and those fall to an ancestor rather than to the
-        # section they merely trail.
+        # Bounds nest, so the last one covering a line is what prints it
         holders = [
             position
             for position, (start, end) in sections
@@ -577,8 +555,7 @@ def _echo_outline(content: str, language: str) -> None:
     example = _example_reference(headings)
     if example:
         count = sum(1 for heading in headings if heading.index)
-        # stdout is block-buffered when redirected, so without this the hint
-        # lands above the outline it is meant to follow
+        # Redirected stdout is block-buffered, so the hint would land first
         sys.stdout.flush()
         click.echo(
             f"# {count} sections · print one:  "
@@ -656,8 +633,7 @@ def _select_section(content: str, reference: str, language: str) -> str:
     if not matches:
         _report_no_heading(content, headings, reference, language)
 
-    # Reporting every candidate beats returning the first one silently, since
-    # guides repeat headings ('Decision' appears under every Python rule).
+    # Guides repeat headings, so name every candidate rather than guess
     if len(matches) > 1:
         click.echo(
             f"Error: '{reference}' matches {len(matches)} headings in the "

{readability_cli-0.10.0 → readability_cli-0.10.2}/readability/tools.py

@@ -1,13 +1,13 @@
 """Build executable plans for readability's canonical tools."""
 
-import logging
-import os
-import shutil
-import tomllib
 from collections.abc import Sequence
 from dataclasses import dataclass
 from importlib.resources import files
+import logging
+import os
 from pathlib import Path
+import shutil
+import tomllib
 
 logger = logging.getLogger("readability")
 
@@ -21,6 +21,7 @@ class ToolPlan:
     check: tuple[str, ...] = ()
     check_format: tuple[str, ...] = ()
     fix: tuple[str, ...] = ()
+    unsafe_fix: tuple[str, ...] = ()
     format: tuple[str, ...] = ()
     targets: tuple[str, ...] | None = None
     cwd: Path | None = None
@@ -300,10 +301,16 @@ def _plan(
             for exclude in excludes
             for argument in (str(flag), str(exclude))
         ]
+    # Every tool spells its own opt-in, so callers only ask for the intent
+    words_by_phase: dict[str, tuple[str, ...]] = dict(TOOL_PHASES[tool])
+    unsafe_flag = UNSAFE_FLAGS.get(tool)
+    if unsafe_flag and "fix" in words_by_phase:
+        words_by_phase["unsafe_fix"] = (*words_by_phase["fix"], unsafe_flag)
+
     # Named rather than unpacked, so the type checker still sees the fields
     phases = {
         phase: (*binary, *words, *config, *carved, *argv)
-        for phase, words in TOOL_PHASES[tool].items()
+        for phase, words in words_by_phase.items()
     }
     return ToolPlan(
         name=tool,
@@ -313,6 +320,7 @@ def _plan(
         check=phases.get("check", ()),
         check_format=phases.get("check_format", ()),
         fix=phases.get("fix", ()),
+        unsafe_fix=phases.get("unsafe_fix", ()),
         format=phases.get("format", ()),
     )
 
@@ -386,6 +394,9 @@ TOOL_PHASES = {
     "gofmt": {"check_format": ("-l",), "format": ("-w",)},
 }
 
+# Per tool: how it names fixes that may change behavior or drop comments
+UNSAFE_FLAGS = {"ruff": "--unsafe-fixes", "biome": "--unsafe"}
+
 
 def _matching_paths(path: Path, extensions: Sequence[str]) -> list[str]:
     """Return files under a requested path owned by one tool.

{readability_cli-0.10.0 → readability_cli-0.10.2}/test_checking.py

@@ -1,20 +1,21 @@
 import json
+from pathlib import Path
 import subprocess
 import tomllib
-from pathlib import Path
-from unittest.mock import MagicMock, call, patch
+from unittest.mock import call
+from unittest.mock import MagicMock
+from unittest.mock import patch
 
-import pytest
 from click.testing import CliRunner
+import pytest
 
-from readability.checking import CheckReport, check_paths
+from readability.checking import check_paths
+from readability.checking import CheckReport
 from readability.cli import cli
-from readability.tools import (
-    TOOL_RUNNERS,
-    _bundled_config,
-    _get_tool_definitions,
-    _has_project_config,
-)
+from readability.tools import _bundled_config
+from readability.tools import _get_tool_definitions
+from readability.tools import _has_project_config
+from readability.tools import TOOL_RUNNERS
 
 
 def _source_file(directory: Path, name: str) -> Path:
@@ -1035,6 +1036,14 @@ def test_bundled_default_configs_are_valid() -> None:
     assert ruff_config["line-length"] == 80
     assert ruff_config["lint"]["pydocstyle"]["convention"] == "google"
 
+    # Import sorting mirrors isort's google profile
+    assert ruff_config["lint"]["isort"] == {
+        "force-single-line": True,
+        "force-sort-within-sections": True,
+        "single-line-exclusions": ["typing"],
+        "order-by-type": False,
+    }
+
 
 @patch("readability.checking._check_path")
 def test_check_paths_aggregates_str_and_path_inputs(
@@ -1071,8 +1080,16 @@ def test_check_paths_aggregates_str_and_path_inputs(
         failed={"biome"},
     )
     assert mock_check_path.call_args_list == [
-        call(Path("src/example.py"), project_root, project_root, fix=True),
-        call(Path("main.go"), project_root, project_root, fix=True),
+        call(
+            Path("src/example.py"),
+            project_root,
+            project_root,
+            fix=True,
+            unsafe=False,
+        ),
+        call(
+            Path("main.go"), project_root, project_root, fix=True, unsafe=False
+        ),
     ]
 
 
@@ -1119,7 +1136,7 @@ def test_check_paths_defaults_project_root_to_cwd(
     check_paths([Path("example.py")])
 
     mock_check_path.assert_called_once_with(
-        Path("example.py"), tmp_path, None, fix=False
+        Path("example.py"), tmp_path, None, fix=False, unsafe=False
     )
 
 
@@ -1188,7 +1205,9 @@ def test_check_command_delegates_to_public_api(
         Path("script.py").touch()
         result = runner.invoke(cli, ["check", "script.py"])
 
-    mock_check_paths.assert_called_once_with(("script.py",), fix=False)
+    mock_check_paths.assert_called_once_with(
+        ("script.py",), fix=False, unsafe=False
+    )
     assert result.exit_code == 0
     assert result.stdout == ""
     assert result.stderr == "No findings in 1 path(s) (ruff).\n"
@@ -2043,3 +2062,136 @@ def test_fix_still_reports_what_it_could_not_fix(
     commands = [call.args[0] for call in mock_run.call_args_list]
     assert any("--fix" not in c and "check" in c for c in commands)
     assert result.exit_code != 0
+
+
+@patch("shutil.which")
+@patch("subprocess.run")
+def test_unsafe_translates_to_the_ruff_flag(
+    mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path
+) -> None:
+    """--unsafe reaches ruff under the name ruff gives it.
+
+    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 name: name if name == "ruff" else None
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("pyproject.toml").touch()
+        Path("script.py").touch()
+
+        result = runner.invoke(cli, ["check", "--fix", "--unsafe", "script.py"])
+
+    assert result.exit_code == 0
+    cfg = str(_bundled_config("ruff"))
+    called_cmds = [call.args[0] for call in mock_run.call_args_list]
+    assert [
+        "ruff",
+        "check",
+        "--fix",
+        "--force-exclude",
+        "--unsafe-fixes",
+        "--config",
+        cfg,
+        "script.py",
+    ] in called_cmds
+    # Formatters have no unsafe mode, so the flag must not reach them
+    assert [
+        "ruff",
+        "format",
+        "--force-exclude",
+        "--config",
+        cfg,
+        "script.py",
+    ] in called_cmds
+
+
+@patch("shutil.which")
+@patch("subprocess.run")
+def test_unsafe_translates_to_the_biome_flag(
+    mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path
+) -> None:
+    """Biome spells the same intent differently and gets its own spelling.
+
+    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 name: name if name == "biome" else None
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("script.ts").touch()
+
+        result = runner.invoke(cli, ["check", "--fix", "--unsafe", "script.ts"])
+
+    assert result.exit_code == 0
+    called_cmds = [call.args[0] for call in mock_run.call_args_list]
+    lint = next(c for c in called_cmds if "lint" in c)
+    assert lint[:5] == [
+        "biome",
+        "lint",
+        "--write",
+        "--no-errors-on-unmatched",
+        "--unsafe",
+    ]
+
+
+@patch("shutil.which")
+@patch("subprocess.run")
+def test_unsafe_implies_fix(
+    mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path
+) -> None:
+    """Asking for unsafe fixes without --fix asks for nothing otherwise.
+
+    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 name: name if name == "ruff" else None
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("pyproject.toml").touch()
+        Path("script.py").touch()
+
+        result = runner.invoke(cli, ["check", "--unsafe", "script.py"])
+
+    assert result.exit_code == 0
+    called_cmds = [call.args[0] for call in mock_run.call_args_list]
+    assert any("--unsafe-fixes" in command for command in called_cmds)
+
+
+@patch("shutil.which")
+@patch("subprocess.run")
+def test_unsafe_is_a_no_op_for_tools_without_one(
+    mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path
+) -> None:
+    """A tool with no unsafe mode still fixes rather than being skipped.
+
+    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 name: name if name == "gofmt" else None
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+
+    runner = CliRunner()
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        Path("main.go").touch()
+
+        result = runner.invoke(cli, ["check", "--fix", "--unsafe", "main.go"])
+
+    assert result.exit_code == 0
+    assert [invocation.args[0] for invocation in mock_run.call_args_list] == [
+        ["gofmt", "-w", "main.go"]
+    ]

{readability_cli-0.10.0 → readability_cli-0.10.2}/test_guide.py

@@ -1,20 +1,19 @@
 import os
 from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock
+from unittest.mock import patch
 
 import click
+from click.testing import CliRunner
 import pytest
 import requests
-from click.testing import CliRunner
 
 from readability.cli import cli
-from readability.guide import (
-    convert_to_markdown,
-    get_guide,
-    get_guide_content,
-    get_guides_dir,
-    get_local_path,
-)
+from readability.guide import convert_to_markdown
+from readability.guide import get_guide
+from readability.guide import get_guide_content
+from readability.guide import get_guides_dir
+from readability.guide import get_local_path
 
 
 def test_get_guide_unsupported() -> None:
@@ -159,8 +158,7 @@ def test_sync_command(
         result = runner.invoke(cli, ["sync"])
 
         assert result.exit_code == 0
-        # Progress is an outcome the caller asked for, so it is reported
-        # regardless of log level rather than logged as narration.
+        # An asked-for outcome, so reported regardless of log level
         assert "Sync complete" in result.stderr
         # Check if at least one guide was "synced" (written to tmp_path)
         assert len(os.listdir(tmp_path)) > 0

{readability_cli-0.10.0 → readability_cli-0.10.2}/test_outline.py

@@ -1,23 +1,21 @@
 import logging
 import os
 from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock
+from unittest.mock import patch
 
 from click.testing import CliRunner
 
-from readability.cli import cli, main
-from readability.guide import (
-    LANGUAGE_MAP,
-    get_local_path,
-)
-from readability.outline import (
-    _iter_heading_lines,
-    _unique_reference,
-    extract_section,
-    find_headings,
-    find_mentions,
-    parse_headings,
-)
+from readability.cli import cli
+from readability.cli import main
+from readability.guide import get_local_path
+from readability.guide import LANGUAGE_MAP
+from readability.outline import _iter_heading_lines
+from readability.outline import _unique_reference
+from readability.outline import extract_section
+from readability.outline import find_headings
+from readability.outline import find_mentions
+from readability.outline import parse_headings
 
 NUMBERED_GUIDE = """# Sample Style Guide
 
@@ -456,10 +454,7 @@ def test_cli_section_heading_containing_an_angle_bracket(
     assert "Array body." in result.stdout
 
 
-# The heading scanner is deliberately not a Markdown parser (see the note on
-# _iter_heading_lines). These tests are the evidence for that decision: the
-# scope it covers, the constructs it rejects, and its behaviour over every
-# guide actually shipped. A failure here means the scope has been outgrown.
+# Evidence the scanner need not be a Markdown parser; a failure means it is
 
 
 def test_heading_scanner_rejects_non_headings() -> None:
@@ -551,8 +546,7 @@ def test_every_shipped_guide_parses_into_unique_sections() -> None:
             f"{language}: duplicate positional indices"
         )
 
-        # A heading taken from inside a fence would carry a comment marker
-        # or a shebang, neither of which appears in a real guide heading.
+        # A fenced line would carry a comment marker or a shebang
         for heading in headings:
             assert not heading.title.startswith("!"), (
                 f"{language}: shebang parsed as heading: {heading.title!r}"
@@ -575,9 +569,7 @@ def test_every_shipped_guide_heading_is_addressable() -> None:
         )
         assert titles[0] is headings[0], f"{language}: title is not first"
 
-        # An index alone is not always enough: where a guide prints its own
-        # numbers those drift from the tree, so one string can name two
-        # headings. What must always hold is that some reference resolves.
+        # A guide's own numbers drift, so only 'some reference resolves' holds
         for position, heading in enumerate(headings):
             reference = _unique_reference(headings, position).strip('"')
             matches = find_headings(headings, reference)
@@ -587,9 +579,7 @@ def test_every_shipped_guide_heading_is_addressable() -> None:
             )
 
 
-# Words the corpus uses often enough to exercise many sections at once.
-# 'truefalse' appears only inside pyguide's anchors, which is the shape that
-# used to be credited to whichever section happened to precede them.
+# Common words, plus 'truefalse' which appears only inside pyguide's anchors
 MENTION_PROBES = (
     "truefalse",
     "indent",

{readability_cli-0.10.0 → readability_cli-0.10.2}/test_package.py

@@ -1,8 +1,10 @@
 from importlib.resources import files
 
 import readability
-from readability.checking import CheckReport, check_paths
-from readability.cli import cli, main
+from readability.checking import check_paths
+from readability.checking import CheckReport
+from readability.cli import cli
+from readability.cli import main
 
 
 def test_public_modules_are_importable() -> None:

{readability_cli-0.10.0 → readability_cli-0.10.2}/uv.lock

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