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

{readability_cli-0.8.5 → readability_cli-0.9.0}/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: astral-sh/setup-uv@v7
         with:
-          python-version: '3.14'
+          python-version: "3.14"
 
       - name: Install dependencies
         run: uv sync

{readability_cli-0.8.5 → readability_cli-0.9.0}/.github/workflows/publish.yml

@@ -2,7 +2,7 @@ name: Publish
 
 on:
   push:
-    tags: ['v*']
+    tags: ["v*"]
 
 jobs:
   publish:
@@ -17,7 +17,7 @@ jobs:
       - name: Set up Python
         uses: astral-sh/setup-uv@v7
         with:
-          python-version: '3.14'
+          python-version: "3.14"
 
       - name: Build distribution
         run: uv build

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

@@ -2,7 +2,7 @@ name: Update Style Guides
 
 on:
   schedule:
-    - cron: '0 0 * * 0' # Weekly on Sunday at midnight
+    - cron: "0 0 * * 0" # Weekly on Sunday at midnight
   workflow_dispatch: # Ad-hoc trigger
 
 jobs:
@@ -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.5 → readability_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.8.5
+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
@@ -17,22 +17,21 @@ Description-Content-Type: text/markdown
 A CLI tool that keeps code aligned with Google style conventions. It runs the
 right linters, formatters, and type checkers for your project with sensible
 defaults, and serves the official Google style guides in Markdown format. This
-is ideal for AI agents or developers who want consistent code quality checks
-and quick access to style conventions without browsing HTML pages.
+is ideal for AI agents or developers who want consistent code quality checks and
+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**: Bundled Google-style configurations for Ruff,
-  Pyrefly, and Biome 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 to be read whole.
-- **Offline Mode**: Local caching of style guides for fast, offline access,
-  kept fresh with a single `sync` command.
+  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
+  to be read whole.
+- **Offline Mode**: Local caching of style guides for fast, offline access, kept
+  fresh with a single `sync` command.
 
 ## Quick Start
 
@@ -79,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
@@ -93,56 +92,57 @@ 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` | `.prettierrc*` or `prettier.config.*` | `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.
 
-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`. An installed copy always wins over a fetched one, so a project that
-pinned a version is linted against the rules it chose.
+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`.
+An installed copy always wins over a fetched one, so a project that pinned a
+version is linted against the rules it chose.
 
 Fetched tools carry a minimum version, enough to understand the bundled
 configurations, and no maximum. A ceiling would freeze anyone who installed
-nothing at whatever was current when this package shipped, and tie its
-releases to Ruff's — which has published seventeen minor series, roughly one
-every six weeks. If you need a fixed version, install it: an installed tool
-always wins over a fetched one.
+nothing at whatever was current when this package shipped, and tie its releases
+to Ruff's — which has published seventeen minor series, roughly one every six
+weeks. If you need a fixed version, install it: an installed tool always wins
+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.
+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 and gofmt
-bring no defaults here, so they wait until the project asks with a config 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/
 Error: Every tool for 1 path(s) is missing, so nothing was verified.
 ```
 
-That second case needs neither the tool nor a runner to be present, which is
-the state a container image is usually in.
+That second case needs neither the tool nor a runner to be present, which is the
+state a container image is usually in.
 
 `check` exits non-zero on findings, tool failures, and when every applicable
 tool is absent, so it can gate CI without a clean exit meaning required tools
@@ -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:
@@ -165,26 +165,29 @@ if report.findings or report.failed or not report.ran:
 ```
 
 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.
+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.
 
-### 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
+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. 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`, or `biome.jsonc` — 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
 
@@ -210,17 +213,17 @@ readability guide python --full | grep -i f-string
 
 A guide can exceed 200 KB, so the outline is what a bare invocation prints:
 listing the sections and fetching the one you need beats reading the lot.
-Nothing is written to disk, which is what a coding agent should do rather
-than redirecting a guide into the repository it is working on — use a shell
-redirect if you do want a copy.
+Nothing is written to disk, which is what a coding agent should do rather than
+redirecting a guide into the repository it is working on — use a shell redirect
+if you do want a copy.
 
-`REF` and `--full` cannot be combined; that is refused rather than resolved
-by a precedence rule you would have to know.
+`REF` and `--full` cannot be combined; that is refused rather than resolved by a
+precedence rule you would have to know.
 
 ### Navigating a Guide
 
-The outline gives each section an index to fetch it by, and flags the ones
-large enough to be worth knowing about first:
+The outline gives each section an index to fetch it by, and flags the ones large
+enough to be worth knowing about first:
 
 ```bash
 $ readability guide cpp
@@ -234,28 +237,28 @@ Google C++ Style Guide
 # 140 sections · print one:  readability guide cpp 4.5.1
 ```
 
-Sizes appear only at 1200 words and above — the 4% of sections expensive
-enough that you would want warning. They include subsections, since that is
-what the reference returns. The trailing line goes to stderr, so it never
-contaminates a piped outline.
+Sizes appear only at 1200 words and above — the 4% of sections expensive enough
+that you would want warning. They include subsections, since that is what the
+reference returns. The trailing line goes to stderr, so it never contaminates a
+piped outline.
 
 A section reference can be any of the following:
 
-| Reference | Example |
-|-----------|---------|
-| Section index, as shown by the outline | `2.2.4` |
-| Heading text, case-insensitive, or its slug | `"function comments"` |
+| Reference                                   | Example                |
+| ------------------------------------------- | ---------------------- |
+| Section index, as shown by the outline      | `2.2.4`                |
+| Heading text, case-insensitive, or its slug | `"function comments"`  |
 | A parent-scoped path, spaces around the `>` | `"Imports > Decision"` |
 
-Whole matches are preferred; a reference that matches nothing in full is
-retried as a substring of the heading text.
+Whole matches are preferred; a reference that matches nothing in full is retried
+as a substring of the heading text.
 
 Three of the shipped guides — Python, JavaScript, and Java — number their own
 sections, and those numbers are the index. A rule cited from the outline then
-matches the published guide exactly, including where the guide skips a
-number: the Python guide has no 2.15 at all, so its 2.16 is listed as 2.16
-rather than renumbered. The other eleven guides number nothing, so their
-index comes from each heading's position in the tree.
+matches the published guide exactly, including where the guide skips a number:
+the Python guide has no 2.15 at all, so its 2.16 is listed as 2.16 rather than
+renumbered. The other eleven guides number nothing, so their index comes from
+each heading's position in the tree.
 
 Either way the index is unique, which is what makes a repeated heading
 addressable — `Definition`, `Pros`, `Cons`, and `Decision` appear under every
@@ -278,8 +281,8 @@ Error: 'Decision' matches 19 headings in the 'python' guide. Repeat with one of:
 
 A guide discusses plenty that no heading is named after, so a reference that
 matches nothing is usually a vocabulary mismatch rather than a mistake. The
-sections that mention the words are reported, which turns the miss into the
-next command:
+sections that mention the words are reported, which turns the miss into the next
+command:
 
 ```bash
 $ readability guide python f-string
@@ -289,22 +292,21 @@ It appears in these sections:
   3.10.1  Python Style Rules > Strings > Logging
 ```
 
-This locates a rule; it does not search text. For that, pipe `--full` to
-`grep`, which you already know and which brings its own `-i`, `-A`, `-c` and
-the rest:
+This locates a rule; it does not search text. For that, pipe `--full` to `grep`,
+which you already know and which brings its own `-i`, `-A`, `-c` and the rest:
 
 ```bash
 readability guide python --full | grep -in -A2 "f-string"
 ```
 
-Content goes to stdout and diagnostics to stderr, so every form is safe to
-pipe. Headings inside fenced code blocks are ignored, which matters for the
-Shell and Python guides where `#` starts a comment.
+Content goes to stdout and diagnostics to stderr, so every form is safe to pipe.
+Headings inside fenced code blocks are ignored, which matters for the Shell and
+Python guides where `#` starts a comment.
 
 ### Supported Languages
 
-Run `readability guide` with no language for the full list and which guides
-are cached:
+Run `readability guide` with no language for the full list and which guides are
+cached:
 
 ```bash
 $ readability guide
@@ -337,17 +339,17 @@ readability sync
 
 ### Offline Mode
 
-The tool stores local copies of the style guides in the `guides/` directory
-and the `guide` command uses these local files when they exist. The bundled
-copies are automatically synchronized weekly from the official
+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.
+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:
+the guides in a specific location or share them across different installations:
 
 ```bash
 export READABILITY_CACHE=/path/to/my/guides