readability-cli 0.8.6__tar.gz → 0.9.0__tar.gz

{readability_cli-0.8.6 → readability_cli-0.9.0}/.github/workflows/update-guides.yml

@@ -30,4 +30,4 @@ jobs:
         uses: stefanzweifel/git-auto-commit-action@v5
         with:
           commit_message: "chore: update style guides [skip ci]"
-          file_pattern: "guides/*.md"
+          file_pattern: "readability/guides/*.md"

{readability_cli-0.8.6 → readability_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.8.6
+Version: 0.9.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
@@ -23,9 +23,9 @@ quick access to style conventions without browsing HTML pages.
 ## Features
 
 - **Linting & Formatting**: A `check` command that automatically detects and
-  runs relevant tools (Ruff, Pyrefly, Biome, Prettier, gofmt) for your project.
-- **Sensible Defaults**: Google-style defaults for Ruff, Pyrefly, Biome, and
-  Prettier are used automatically when a project does not define its own.
+  runs relevant tools (Ruff, Pyrefly, Biome, and gofmt) for your project.
+- **Predictable Ownership**: Every supported format has fixed tools, so
+  configuration customizes checks without changing which formatter runs.
 - **Style Guides**: A `guide` command that fetches the latest Google style
   guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown, and
   outlines, addresses, and searches them by section rather than serving 200 KB
@@ -78,8 +78,8 @@ uv run readability sync
 ## Checking and Formatting
 
 The `check` command identifies and runs relevant linting and formatting tools
-based on file extensions and the presence of configuration files (triggers) in
-your project root:
+solely from file extensions. Configuration can customize the assigned tools,
+but cannot opt another tool into a format:
 
 ```bash
 # Run checks on the current directory
@@ -92,21 +92,22 @@ readability check src/ tests/ main.py
 readability check . --fix
 ```
 
-### Supported Tools
+### Supported Formats
 
-| Tool         | Supported Extensions                                                                    | Config Needed                     | Fetched By |
-| ------------ | --------------------------------------------------------------------------------------- | --------------------------------- | ---------- |
-| **Ruff**     | `.py`                                                                                   | none, bundled                     | `uvx`      |
-| **Pyrefly**  | `.py`                                                                                   | none, bundled                     | `uvx`      |
-| **Biome**    | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html`                        | none, bundled                     | `npx`      |
-| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | none for Markdown, YAML, and SCSS | `npx`      |
-| **gofmt**    | `.go`                                                                                   | `go.mod`                          | —          |
+| Formats                                                          | Owners                                  | Project configuration                 |
+| ---------------------------------------------------------------- | --------------------------------------- | ------------------------------------- |
+| `.py`                                                            | Ruff lint/format; Pyrefly type checking | Ruff and Pyrefly native configuration |
+| `.js`, `.jsx`, `.ts`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html` | Biome                                   | `biome.json` or `biome.jsonc`         |
+| `.go`                                                            | gofmt                                   | None                                  |
 
-**You do not need to install any of these.** Each is resolved in order: a
-project-local install (`node_modules/.bin`, `.venv/bin`) first, then whatever is
-on your `PATH`, and only then fetched by `uvx` or `npx`. The runners cache what
-they download, so the fetch happens once per machine and later runs are served
-from disk and work offline.
+Markdown, YAML, SCSS, JSONL, and extensions not listed above are unsupported.
+An unsupported-only path reports that nothing was checked and exits
+successfully.
+
+Biome first checks a project's `node_modules/.bin`. Ruff, Pyrefly, and Biome
+then use `PATH`, followed by `uvx` for the Python tools or `npx` for Biome. The
+runners cache downloads, so subsequent runs work offline. Gofmt ships with Go
+and must be available on `PATH`.
 
 That keeps this package at ~4 MB rather than the ~54 MB it would take to carry
 Ruff and Pyrefly itself — a cost that would fall on everyone using only `guide`.
@@ -123,18 +124,17 @@ over a fetched one.
 Set `UV_OFFLINE=1` to forbid fetching. A tool that then cannot be reached fails
 the run rather than passing it.
 
-Ruff, Pyrefly, and Biome ship with bundled configurations, so they run on any
-file they handle without the project arranging anything. Prettier does the same
-for Markdown, YAML, and SCSS; a Prettier configuration opts its overlapping web
-formats into Prettier too. Gofmt waits for a `go.mod` file.
+Ruff, Pyrefly, and Biome ship with bundled configurations, so they run on every
+file they own without project setup. Gofmt runs on `.go` files even when there
+is no `go.mod`.
 
 A tool that could not be reached at all is never skipped quietly:
 
 ```bash
 # Some tools ran, so the result stands, but coverage was partial
 $ readability check src/
-Warning: not installed, so not run: prettier.
-No findings in 1 path(s) (ruff, pyrefly).
+Warning: not installed, so not run: pyrefly.
+No findings in 1 path(s) (ruff).
 
 # Nothing ran, so there is no result to report
 $ readability check src/
@@ -157,7 +157,7 @@ or exit-code decisions:
 ```python
 from pathlib import Path
 
-from readability import check_paths
+from readability.checking import check_paths
 
 report = check_paths(["src", Path("tests")], project_root=Path.cwd())
 if report.findings or report.failed or not report.ran:
@@ -171,22 +171,23 @@ 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
+### Configuring Formats
 
 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
 [Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html)
-and enables Biome's recommended lint rules. Prettier wraps prose at 80 columns,
-following the
-[Google Markdown style guide](https://google.github.io/styleguide/docguide/style.html#character-line-limit).
-These defaults apply only when the project does not define its own
-configuration. To override them, add a `[tool.ruff]` or `[tool.pyrefly]` section
-to your `pyproject.toml`, or a dedicated `ruff.toml`, `pyrefly.toml`,
-`biome.json`, `biome.jsonc`, or Prettier configuration — any project-level
-configuration takes full precedence. The bundled Biome file requires Biome 2.5
-or later, matching the version floor used by the fallback runner.
+and enables Biome's recommended lint rules. Project `biome.json` and
+`biome.jsonc` files replace those bundled defaults for Biome-owned formats.
+
+For Python, add `[tool.ruff]` or `[tool.pyrefly]` to `pyproject.toml`, or use
+`ruff.toml`, `.ruff.toml`, or `pyrefly.toml`. Ruff, Pyrefly, and Biome load
+their native project configurations in place of bundled defaults. Readability
+does not interpret EditorConfig itself; a canonical tool such as Biome may opt
+into it through that tool's native configuration. Gofmt has no project settings.
+The bundled Biome file requires Biome 2.5 or later, matching the fallback
+runner's version floor.
 
 ## Style Guides
 
@@ -338,14 +339,15 @@ readability sync
 
 ### Offline Mode
 
-The tool stores local copies of the style guides in the `guides/` directory and
+The tool stores local copies of the style guides in the
+`readability/guides/` directory and
 the `guide` command uses these local files when they exist. The bundled copies
 are automatically synchronized weekly from the official
 [Google Style Guides](https://google.github.io/styleguide/) repository via
 GitHub Actions, and you can refresh your local cache at any time with the `sync`
 command.
 
-You can override the default `guides/` directory by setting the
+You can override the default guide directory by setting the
 `READABILITY_CACHE` environment variable. This is useful if you want to store
 the guides in a specific location or share them across different installations:
 

{readability_cli-0.8.6 → readability_cli-0.9.0}/README.md

@@ -9,9 +9,9 @@ quick access to style conventions without browsing HTML pages.
 ## Features
 
 - **Linting & Formatting**: A `check` command that automatically detects and
-  runs relevant tools (Ruff, Pyrefly, Biome, Prettier, gofmt) for your project.
-- **Sensible Defaults**: Google-style defaults for Ruff, Pyrefly, Biome, and
-  Prettier are used automatically when a project does not define its own.
+  runs relevant tools (Ruff, Pyrefly, Biome, and gofmt) for your project.
+- **Predictable Ownership**: Every supported format has fixed tools, so
+  configuration customizes checks without changing which formatter runs.
 - **Style Guides**: A `guide` command that fetches the latest Google style
   guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown, and
   outlines, addresses, and searches them by section rather than serving 200 KB
@@ -64,8 +64,8 @@ uv run readability sync
 ## Checking and Formatting
 
 The `check` command identifies and runs relevant linting and formatting tools
-based on file extensions and the presence of configuration files (triggers) in
-your project root:
+solely from file extensions. Configuration can customize the assigned tools,
+but cannot opt another tool into a format:
 
 ```bash
 # Run checks on the current directory
@@ -78,21 +78,22 @@ readability check src/ tests/ main.py
 readability check . --fix
 ```
 
-### Supported Tools
+### Supported Formats
 
-| Tool         | Supported Extensions                                                                    | Config Needed                     | Fetched By |
-| ------------ | --------------------------------------------------------------------------------------- | --------------------------------- | ---------- |
-| **Ruff**     | `.py`                                                                                   | none, bundled                     | `uvx`      |
-| **Pyrefly**  | `.py`                                                                                   | none, bundled                     | `uvx`      |
-| **Biome**    | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html`                        | none, bundled                     | `npx`      |
-| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | none for Markdown, YAML, and SCSS | `npx`      |
-| **gofmt**    | `.go`                                                                                   | `go.mod`                          | —          |
+| Formats                                                          | Owners                                  | Project configuration                 |
+| ---------------------------------------------------------------- | --------------------------------------- | ------------------------------------- |
+| `.py`                                                            | Ruff lint/format; Pyrefly type checking | Ruff and Pyrefly native configuration |
+| `.js`, `.jsx`, `.ts`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html` | Biome                                   | `biome.json` or `biome.jsonc`         |
+| `.go`                                                            | gofmt                                   | None                                  |
 
-**You do not need to install any of these.** Each is resolved in order: a
-project-local install (`node_modules/.bin`, `.venv/bin`) first, then whatever is
-on your `PATH`, and only then fetched by `uvx` or `npx`. The runners cache what
-they download, so the fetch happens once per machine and later runs are served
-from disk and work offline.
+Markdown, YAML, SCSS, JSONL, and extensions not listed above are unsupported.
+An unsupported-only path reports that nothing was checked and exits
+successfully.
+
+Biome first checks a project's `node_modules/.bin`. Ruff, Pyrefly, and Biome
+then use `PATH`, followed by `uvx` for the Python tools or `npx` for Biome. The
+runners cache downloads, so subsequent runs work offline. Gofmt ships with Go
+and must be available on `PATH`.
 
 That keeps this package at ~4 MB rather than the ~54 MB it would take to carry
 Ruff and Pyrefly itself — a cost that would fall on everyone using only `guide`.
@@ -109,18 +110,17 @@ over a fetched one.
 Set `UV_OFFLINE=1` to forbid fetching. A tool that then cannot be reached fails
 the run rather than passing it.
 
-Ruff, Pyrefly, and Biome ship with bundled configurations, so they run on any
-file they handle without the project arranging anything. Prettier does the same
-for Markdown, YAML, and SCSS; a Prettier configuration opts its overlapping web
-formats into Prettier too. Gofmt waits for a `go.mod` file.
+Ruff, Pyrefly, and Biome ship with bundled configurations, so they run on every
+file they own without project setup. Gofmt runs on `.go` files even when there
+is no `go.mod`.
 
 A tool that could not be reached at all is never skipped quietly:
 
 ```bash
 # Some tools ran, so the result stands, but coverage was partial
 $ readability check src/
-Warning: not installed, so not run: prettier.
-No findings in 1 path(s) (ruff, pyrefly).
+Warning: not installed, so not run: pyrefly.
+No findings in 1 path(s) (ruff).
 
 # Nothing ran, so there is no result to report
 $ readability check src/
@@ -143,7 +143,7 @@ or exit-code decisions:
 ```python
 from pathlib import Path
 
-from readability import check_paths
+from readability.checking import check_paths
 
 report = check_paths(["src", Path("tests")], project_root=Path.cwd())
 if report.findings or report.failed or not report.ran:
@@ -157,22 +157,23 @@ 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
+### Configuring Formats
 
 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
 [Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html)
-and enables Biome's recommended lint rules. Prettier wraps prose at 80 columns,
-following the
-[Google Markdown style guide](https://google.github.io/styleguide/docguide/style.html#character-line-limit).
-These defaults apply only when the project does not define its own
-configuration. To override them, add a `[tool.ruff]` or `[tool.pyrefly]` section
-to your `pyproject.toml`, or a dedicated `ruff.toml`, `pyrefly.toml`,
-`biome.json`, `biome.jsonc`, or Prettier configuration — any project-level
-configuration takes full precedence. The bundled Biome file requires Biome 2.5
-or later, matching the version floor used by the fallback runner.
+and enables Biome's recommended lint rules. Project `biome.json` and
+`biome.jsonc` files replace those bundled defaults for Biome-owned formats.
+
+For Python, add `[tool.ruff]` or `[tool.pyrefly]` to `pyproject.toml`, or use
+`ruff.toml`, `.ruff.toml`, or `pyrefly.toml`. Ruff, Pyrefly, and Biome load
+their native project configurations in place of bundled defaults. Readability
+does not interpret EditorConfig itself; a canonical tool such as Biome may opt
+into it through that tool's native configuration. Gofmt has no project settings.
+The bundled Biome file requires Biome 2.5 or later, matching the fallback
+runner's version floor.
 
 ## Style Guides
 
@@ -324,14 +325,15 @@ readability sync
 
 ### Offline Mode
 
-The tool stores local copies of the style guides in the `guides/` directory and
+The tool stores local copies of the style guides in the
+`readability/guides/` directory and
 the `guide` command uses these local files when they exist. The bundled copies
 are automatically synchronized weekly from the official
 [Google Style Guides](https://google.github.io/styleguide/) repository via
 GitHub Actions, and you can refresh your local cache at any time with the `sync`
 command.
 
-You can override the default `guides/` directory by setting the
+You can override the default guide directory by setting the
 `READABILITY_CACHE` environment variable. This is useful if you want to store
 the guides in a specific location or share them across different installations:
 

{readability_cli-0.8.6 → readability_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.8.6"
+version = "0.9.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"
@@ -16,17 +16,13 @@ Homepage = "https://github.com/owahltinez/readability"
 Repository = "https://github.com/owahltinez/readability"
 
 [project.scripts]
-readability = "readability:main"
+readability = "readability.cli:main"
 
 [tool.uv]
 package = true
 
 [tool.hatch.build.targets.wheel]
-include = [
-    "/readability.py",
-    "/guides",
-    "/configs",
-]
+packages = ["readability"]
 
 [build-system]
 requires = ["hatchling"]
@@ -54,3 +50,4 @@ convention = "google"
 [tool.ruff.lint.per-file-ignores]
 "test_*.py" = ["D"]
 "*_test.py" = ["D"]
+"readability/__init__.py" = ["D104"]

readability_cli-0.9.0/readability/checking.py

@@ -0,0 +1,265 @@
+"""Run readability checks and report their coverage."""
+
+import dataclasses
+import logging
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+
+import click
+
+from readability.tools import (
+    ToolPlan,
+    _command_batches,
+    _get_tool_definitions,
+    _should_run_tool,
+    _tool_is_installed,
+)
+
+logger = logging.getLogger("readability")
+DEFAULT_TIMEOUT = 60
+
+
+@dataclasses.dataclass
+class CheckReport:
+    """What a check actually did, as opposed to what it was asked to do.
+
+    Attributes:
+        findings: Whether any tool that ran reported something.
+        ran: Names of the tools that processed at least one file. This records
+            what happened, not what was intended. A tool that resolved but
+            never started belongs in failed, and a tool that explicitly
+            reported processing no files is not recorded as having run.
+        skipped: Names of the tools that were applicable but not installed.
+            Tools that own no requested file are in neither set, so passing
+            without them is not a gap in coverage.
+        failed: Names of the tools that started and could not finish, by
+            failing to exec or by running past the timeout.
+        unverified_paths: Requested paths for which no tool processed a file.
+            Keeping these paths through aggregation prevents a checked path
+            from hiding another path that a tool ignored.
+    """
+
+    findings: bool = False
+    ran: set[str] = dataclasses.field(default_factory=set)
+    skipped: set[str] = dataclasses.field(default_factory=set)
+    failed: set[str] = dataclasses.field(default_factory=set)
+    unverified_paths: list[Path] = dataclasses.field(default_factory=list)
+
+    def absorb(self, other: "CheckReport") -> None:
+        """Fold another report into this one.
+
+        Args:
+            other: The report to merge, typically for one more path.
+        """
+        self.findings |= other.findings
+        self.ran |= other.ran
+        self.skipped |= other.skipped
+        self.failed |= other.failed
+        self.unverified_paths.extend(other.unverified_paths)
+
+
+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:
+        path_report = _check_path(path, root, fix=fix)
+        if not path_report.ran:
+            path_report.unverified_paths.append(path)
+        report.absorb(path_report)
+    return report
+
+
+def _check_path(
+    path: Path, project_root: Path, fix: bool = False
+) -> CheckReport:
+    """Apply relevant tools to a single path.
+
+    Args:
+        path: The path (file or directory) to check.
+        project_root: The root used for native tool configuration discovery.
+        fix: Whether to apply automatic fixes.
+
+    Returns:
+        What the tools applicable to this path did.
+    """
+    logger.info("Checking path: %s", path)
+
+    # Iterate through all supported tool definitions
+    report = CheckReport()
+    for tool in _get_tool_definitions(path, project_root):
+        if not _should_run_tool(tool, path):
+            continue
+
+        # A tool that is wanted but absent leaves a hole in the coverage,
+        # which is not the same as a clean result
+        if not _tool_is_installed(tool):
+            report.skipped.add(tool.name)
+            continue
+
+        report.absorb(_run_tool(tool, fix=fix))
+
+    return report
+
+
+def _run_tool(
+    tool: ToolPlan,
+    fix: 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.
+
+    Returns:
+        What the tool did: whether it reported findings, and whether it
+        completed at all. A tool that could not be started or ran past the
+        timeout verified nothing, and saying so is the difference between a
+        pass and a command that only looks like one.
+    """
+    logger.info("Running %s...", tool.name)
+
+    report = CheckReport()
+    target_count = len(tool.targets or ())
+    try:
+        if fix:
+            # Formatters rewrite files, fixers apply what they can. Both
+            # exit non-zero when something is left over, which is a finding
+            # rather than a failure, so the check below still gets to run
+            # and report what they could not deal with.
+            for phase in ("format", "fix"):
+                configured_command = getattr(tool, phase)
+                if configured_command:
+                    commands = _command_batches(
+                        configured_command, target_count
+                    )
+                    for command in commands:
+                        result = _capture_tool_command(command, cwd=tool.cwd)
+                        if _tool_checked_files(tool.name, result):
+                            report.ran.add(tool.name)
+                        if result.returncode != 0:
+                            report.findings = True
+                            finding_type = (
+                                "formatting findings"
+                                if phase == "format"
+                                else "findings"
+                            )
+                            click.echo(
+                                f"--- {tool.name} {finding_type} ---\n"
+                                f"{result.stdout}\n{result.stderr}"
+                            )
+        elif tool.check_format:
+            for command in _command_batches(tool.check_format, target_count):
+                result = _capture_tool_command(command, cwd=tool.cwd)
+                if _tool_checked_files(tool.name, result):
+                    report.ran.add(tool.name)
+                # gofmt reports by naming files rather than by exit code
+                if result.returncode != 0 or (
+                    tool.name == "gofmt" and result.stdout.strip()
+                ):
+                    report.findings = True
+                    click.echo(
+                        f"--- {tool.name} formatting findings ---\n"
+                        f"{result.stdout}\n{result.stderr}"
+                    )
+
+        if tool.check:
+            for command in _command_batches(tool.check, target_count):
+                result = _capture_tool_command(command, cwd=tool.cwd)
+                if _tool_checked_files(tool.name, result):
+                    report.ran.add(tool.name)
+                if result.returncode != 0:
+                    report.findings = True
+                    click.echo(
+                        f"--- {tool.name} findings ---\n"
+                        f"{result.stdout}\n{result.stderr}"
+                    )
+
+    # Failing to start, or running past the timeout, means this tool checked
+    # nothing. Whatever it managed before that stays in ran.
+    except (subprocess.SubprocessError, OSError) as e:
+        logger.warning("Could not run %s: %s", tool.name, e)
+        report.failed.add(tool.name)
+
+    return report
+
+
+def _tool_checked_files(
+    tool_name: str, result: subprocess.CompletedProcess
+) -> bool:
+    """Report whether a completed command actually processed any files.
+
+    Args:
+        tool_name: The tool whose command completed.
+        result: The completed subprocess.
+
+    Returns:
+        False when Biome explicitly reports that it checked zero files.
+    """
+    if tool_name != "biome":
+        return True
+    output = f"{result.stdout or ''}\n{result.stderr or ''}"
+    # Biome 2.x uses these summaries for an unmatched target.
+    zero_file_summaries = ("Checked 0 files", "Formatted 0 files")
+    return not any(summary in output for summary in zero_file_summaries)
+
+
+def _capture_tool_command(
+    cmd: list[str], cwd: Path | None = None
+) -> subprocess.CompletedProcess:
+    """Run a tool and capture what it said, whatever its exit code.
+
+    Args:
+        cmd: The command list to execute.
+        cwd: Directory in which the tool should run. Defaults to the caller's
+            current working directory.
+
+    Returns:
+        The completed process, including captured output and its exit code.
+
+    Raises:
+        subprocess.SubprocessError: If the command outlives the timeout.
+        OSError: If the command cannot be started.
+    """
+    logger.debug("Executing: %s", " ".join(cmd))
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=DEFAULT_TIMEOUT,
+        cwd=cwd,
+    )