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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.10.1
+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                 |

{readability_cli-0.10.1 → 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                 |

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

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.10.1"
+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"

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

@@ -62,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.
 
@@ -78,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.
@@ -100,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)
@@ -112,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.
 
@@ -121,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.
@@ -141,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
 
@@ -149,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
@@ -168,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.1 → readability_cli-0.10.2}/readability/cli.py

@@ -167,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
@@ -177,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.1 → readability_cli-0.10.2}/readability/tools.py

@@ -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.1 → readability_cli-0.10.2}/test_checking.py

@@ -1080,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
+        ),
     ]
 
 
@@ -1128,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
     )
 
 
@@ -1197,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"
@@ -2052,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.1 → readability_cli-0.10.2}/uv.lock

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