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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.9.0
+Version: 0.10.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
@@ -168,8 +168,13 @@ The returned `CheckReport` records only whether findings occurred and which
 tools ran, were skipped, or failed. Detailed tool findings are still written as
 each tool runs. Every path is validated before any tool runs, and a missing one
 raises `FileNotFoundError` rather than being misreported as a finding. Relative
-paths remain relative to the process working directory; `project_root` controls
-configuration discovery only.
+paths remain relative to the process working directory. `project_root` bounds
+configuration discovery, locates project-local tool installs, and roots
+ignore-file discovery. Because it bounds discovery, a caller that passes one
+gets the same verdict for the same files wherever they sit, which is what makes
+the result usable as a baseline. It defaults to the repository the process is
+in, so the command agrees with the tools rather than with the directory the
+caller happened to be standing in.
 
 ### Configuring Formats
 
@@ -189,6 +194,33 @@ 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.
 
+Configuration is found per file, in the file's own directory and then its
+ancestors, which is where each canonical tool looks. A package keeping its
+settings in a subdirectory is checked against them however it is reached:
+
+```bash
+# Uses web/biome.json, not the bundled default
+readability check web/app.ts
+
+# Uses the repository root's [tool.ruff], not the bundled default
+cd pkg && readability check module.py
+
+# pkg/ is checked against pkg/pyproject.toml, the rest against the defaults
+readability check .
+```
+
+A tool is only told which configuration to use when the file has none, because
+each one resolves its own hierarchy: a single Ruff invocation over two packages
+declaring different line lengths reports each against its own. So a mixed tree
+needs no choosing between configurations, and the bundled default never
+overrides one the project declared.
+
+Discovery is per tool, so configuring one leaves the others on their bundled
+defaults. It is also bounded, by the repository the command runs in, or by
+`project_root` when calling `check_paths` directly. Configuration outside that
+boundary is not read, so the same paths get the same answer wherever the
+repository sits.
+
 ## Style Guides
 
 The `guide` command reads a Google style guide, using the local cache when

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

@@ -154,8 +154,13 @@ The returned `CheckReport` records only whether findings occurred and which
 tools ran, were skipped, or failed. Detailed tool findings are still written as
 each tool runs. Every path is validated before any tool runs, and a missing one
 raises `FileNotFoundError` rather than being misreported as a finding. Relative
-paths remain relative to the process working directory; `project_root` controls
-configuration discovery only.
+paths remain relative to the process working directory. `project_root` bounds
+configuration discovery, locates project-local tool installs, and roots
+ignore-file discovery. Because it bounds discovery, a caller that passes one
+gets the same verdict for the same files wherever they sit, which is what makes
+the result usable as a baseline. It defaults to the repository the process is
+in, so the command agrees with the tools rather than with the directory the
+caller happened to be standing in.
 
 ### Configuring Formats
 
@@ -175,6 +180,33 @@ 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.
 
+Configuration is found per file, in the file's own directory and then its
+ancestors, which is where each canonical tool looks. A package keeping its
+settings in a subdirectory is checked against them however it is reached:
+
+```bash
+# Uses web/biome.json, not the bundled default
+readability check web/app.ts
+
+# Uses the repository root's [tool.ruff], not the bundled default
+cd pkg && readability check module.py
+
+# pkg/ is checked against pkg/pyproject.toml, the rest against the defaults
+readability check .
+```
+
+A tool is only told which configuration to use when the file has none, because
+each one resolves its own hierarchy: a single Ruff invocation over two packages
+declaring different line lengths reports each against its own. So a mixed tree
+needs no choosing between configurations, and the bundled default never
+overrides one the project declared.
+
+Discovery is per tool, so configuring one leaves the others on their bundled
+defaults. It is also bounded, by the repository the command runs in, or by
+`project_root` when calling `check_paths` directly. Configuration outside that
+boundary is not read, so the same paths get the same answer wherever the
+repository sits.
+
 ## Style Guides
 
 The `guide` command reads a Google style guide, using the local cache when

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

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.9.0"
+version = "0.10.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.9.0 → readability_cli-0.10.0}/readability/checking.py

@@ -12,6 +12,7 @@ from readability.tools import (
     ToolPlan,
     _command_batches,
     _get_tool_definitions,
+    _repository_root,
     _should_run_tool,
     _tool_is_installed,
 )
@@ -74,8 +75,10 @@ def check_paths(
     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.
+        project_root: Bounds config discovery, so the same files get the
+            same verdict wherever the tree sits, and locates tool installs
+            and ignore files. Defaults to the repository the process is in.
+            It does not rebase paths.
         fix: Whether to apply automatic fixes.
 
     Returns:
@@ -85,7 +88,11 @@ def check_paths(
         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
+    here = Path.cwd()
+    repository = _repository_root(here)
+    root = project_root if project_root is not None else (repository or here)
+    # A named root bounds the search; otherwise each path's repository does
+    boundary = project_root
     requested_paths = [Path(path) for path in paths]
     missing_path = next(
         (path for path in requested_paths if not path.exists()), None
@@ -95,7 +102,7 @@ def check_paths(
 
     report = CheckReport()
     for path in requested_paths:
-        path_report = _check_path(path, root, fix=fix)
+        path_report = _check_path(path, root, boundary, fix=fix)
         if not path_report.ran:
             path_report.unverified_paths.append(path)
         report.absorb(path_report)
@@ -103,13 +110,18 @@ def check_paths(
 
 
 def _check_path(
-    path: Path, project_root: Path, fix: bool = False
+    path: Path,
+    project_root: Path,
+    boundary: Path | None = None,
+    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.
+        project_root: Locates tool installs and ignore files.
+        boundary: Outermost directory config discovery may consider, or
+            None to bound it by the path's own repository.
         fix: Whether to apply automatic fixes.
 
     Returns:
@@ -117,14 +129,16 @@ def _check_path(
     """
     logger.info("Checking path: %s", path)
 
+    if boundary is None:
+        boundary = _repository_root(path) or Path(path.resolve().anchor)
+
     # Iterate through all supported tool definitions
     report = CheckReport()
-    for tool in _get_tool_definitions(path, project_root):
+    for tool in _get_tool_definitions(path, project_root, boundary):
         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
+        # A wanted but absent tool is a hole in coverage, not a clean result
         if not _tool_is_installed(tool):
             report.skipped.add(tool.name)
             continue
@@ -156,10 +170,7 @@ def _run_tool(
     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.
+            # Leftovers exit non-zero, which is a finding rather than a failure
             for phase in ("format", "fix"):
                 configured_command = getattr(tool, phase)
                 if configured_command:
@@ -208,8 +219,7 @@ def _run_tool(
                         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.
+    # Never starting, or timing out, means this tool checked nothing
     except (subprocess.SubprocessError, OSError) as e:
         logger.warning("Could not run %s: %s", tool.name, e)
         report.failed.add(tool.name)
@@ -227,14 +237,19 @@ def _tool_checked_files(
         result: The completed subprocess.
 
     Returns:
-        False when Biome explicitly reports that it checked zero files.
+        False when the tool explicitly reports that it processed no files.
     """
-    if tool_name != "biome":
+    # Biome says this for an unmatched target, Ruff when excludes cover them all
+    zero_file_reports = {
+        "biome": ("Checked 0 files", "Formatted 0 files"),
+        "ruff": ("No Python files found",),
+    }
+    summaries = zero_file_reports.get(tool_name)
+    if summaries is None:
         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)
+    return not any(summary in output for summary in summaries)
 
 
 def _capture_tool_command(

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

@@ -60,8 +60,7 @@ def guide(
         _echo_languages()
         return
 
-    # Refusing beats picking a winner: a silent precedence rule is how the
-    # caller ends up reading the wrong thing without being told.
+    # Refusing beats a silent precedence rule the caller cannot see
     if full and reference:
         raise click.UsageError("--full takes the whole guide, so REF cannot.")
 
@@ -106,8 +105,7 @@ def _resolve_filenames(languages: Sequence[str]) -> list[str]:
                 f"Language '{language}' is not supported. Supported "
                 f"languages: {', '.join(sorted(LANGUAGE_MAP.keys()))}"
             )
-        # Aliases such as 'cpp' and 'c++' resolve to one guide, which is
-        # fetched once however many of its names were given
+        # Aliases share a guide, fetched once however many names were given
         if filename not in filenames:
             filenames.append(filename)
 
@@ -190,8 +188,7 @@ def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
             err=True,
         )
 
-    # A tool that could not start or outlived the timeout checked nothing,
-    # so its silence is not a pass however far the rest of the run got
+    # A tool that never ran checked nothing, so its silence is not a pass
     if report.failed:
         click.echo(
             f"Error: Could not run: {', '.join(sorted(report.failed))}. "
@@ -200,14 +197,11 @@ def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
         )
         sys.exit(1)
 
-    # Findings remain a failed check even when a tool reports that it could
-    # not process any files (for example, a Biome configuration error).
+    # Findings fail the check even if the tool processed no files
     if report.findings:
         sys.exit(1)
 
-    # Having run nothing is not a pass. Reporting it as one is how this
-    # command became a silent no-op wherever its tools were absent, gating
-    # nothing while every caller read the exit code as approval.
+    # Having run nothing is not a pass, it is a silent no-op gating nothing
     if not report.ran and report.skipped:
         click.echo(
             f"Error: Every tool for {len(paths)} path(s) is missing, so "
@@ -216,9 +210,7 @@ def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
         )
         sys.exit(1)
 
-    # No tool applying is a fact about the project rather than a fault: there
-    # is nothing to install and nothing to fix. It still cannot be reported
-    # as a clean result, because nothing was inspected.
+    # No tool applying is a fact, not a fault, but still not a clean result
     if not report.ran:
         click.echo(
             f"No tool applies to {len(paths)} path(s); nothing was checked.",
@@ -235,8 +227,7 @@ def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
             err=True,
         )
 
-    # Findings are the only thing this command printed, so a clean run said
-    # nothing at all and left the caller unable to tell it from a no-op.
+    # Without this a clean run printed nothing and read as a no-op
     click.echo(
         f"No findings in {checked_path_count} path(s) "
         f"({', '.join(sorted(report.ran))}).",
@@ -247,11 +238,7 @@ def check(paths: Sequence[str], fix: bool, verbose: bool) -> None:
 # Main entry point for the CLI
 def main() -> None:
     """Main entry point for the CLI."""
-    # Configure logging here rather than at import time so that importing this
-    # module as a library (e.g. from lemming) has no side effects
-    # WARNING, not INFO: everything logged below it narrates progress, which
-    # is what --verbose is for. Leaving it on meant there was no quiet mode
-    # and the flag could only add DEBUG on top.
+    # Configured here, not at import, so library use has no side effects
     logging.basicConfig(
         level=logging.WARNING,
         format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",