readability-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{readability_cli-0.7.0 → readability_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.7.0
+Version: 0.8.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
@@ -28,7 +28,8 @@ and quick access to style conventions without browsing HTML pages.
   Pyrefly are used automatically when a project does not define its own.
 - **Style Guides**: A `guide` command that fetches the latest Google style
   guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown,
-  navigable by outline and by section rather than read whole.
+  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.
 
@@ -40,8 +41,9 @@ You can run the tool directly without installing it using `uvx`:
 # Check and fix formatting for the current directory
 uvx --from readability-cli readability check . --fix
 
-# Get the Python style guide
+# Outline the Python style guide, then read one of its sections
 uvx --from readability-cli readability guide python
+uvx --from readability-cli readability guide python 2.2
 ```
 
 ## Installation
@@ -92,17 +94,58 @@ readability check . --fix
 
 ### Supported Tools
 
-| Tool | Supported Extensions | Trigger Files |
-|------|----------------------|---------------|
-| **Ruff** | `.py` | `pyproject.toml`, `ruff.toml`, `.ruff.toml` |
-| **Pyrefly** | `.py` | `pyproject.toml`, `pyrefly.toml` |
-| **Biome** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html` | `biome.json`, `biome.jsonc` |
-| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | `.prettierrc*`, `prettier.config.*` |
-| **gofmt** | `.go` | `go.mod` |
+| 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` | `biome.json` or `biome.jsonc` | `npx` |
+| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | `.prettierrc*` or `prettier.config.*` | `npx` |
+| **gofmt** | `.go` | `go.mod` | — |
+
+**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.
+
+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.
+
+Set `UV_OFFLINE=1` to forbid fetching. A tool that then cannot be reached
+fails the run rather than passing it.
+
+Ruff and Pyrefly ship with bundled configurations, so they run on any file
+they handle without the project arranging anything. Biome, Prettier and gofmt
+bring no defaults here, so they wait until the project asks with a config
+file.
+
+A tool that could not be reached at all is never skipped quietly:
 
-The command will only run a tool if its trigger file exists in the current
-working directory and the tool is available in your `PATH`. For `biome` and
-`prettier`, it attempts to run them via `npx`.
+```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).
+
+# 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.
+
+`check` exits non-zero on findings and on having verified nothing, so it can
+gate CI without a clean exit ever meaning "the tools were absent".
 
 ### Default Configurations
 
@@ -116,59 +159,64 @@ project-level configuration takes full precedence over the bundled defaults.
 
 ## Style Guides
 
-The `guide` command prints a Google style guide as Markdown, using the local
-cache when available:
+The `guide` command reads a Google style guide, using the local cache when
+available. It has four forms:
 
 ```bash
-# Get the Python style guide (uses local cache if available)
-readability guide python
-
-# Force fetching the latest version from the web
-readability guide python --remote
+# Which languages have a guide, and which are cached
+readability guide
 
-# Save a style guide to a file
-readability guide cpp --output cpp-style.md
+# The outline of one: every heading, a few KB where the guide is 200
+readability guide python
 
-# Search a guide without printing it: the pipe carries it, you see matches
-readability guide python | grep -n "f-string"
+# One section, by index, heading text, or a parent-scoped path
+readability guide cpp 10.4
+readability guide shell "Function Comments"
+readability guide python "Imports > Decision"
 
-# Synchronize all supported style guides to the local cache
-readability sync
+# The whole guide, for grepping or when you really do want all of it
+readability guide cpp --full
+readability guide python --full | grep -i f-string
 ```
 
-A guide can exceed 100 KB, so printing one whole is rarely what you want.
-`--outline` and `--section` below cover navigating to a rule; piping to
-`grep` covers finding wording that no heading names. Neither leaves a copy
-behind, which is what a coding agent should do rather than redirecting a
-guide into the repository it is working on.
+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.
+
+`REF` and `--full` cannot be combined; that is refused rather than resolved
+by a precedence rule you would have to know.
 
 ### Navigating a Guide
 
-`--outline` lists a guide's headings and `--section` prints just one of them,
-which turns "read 200 KB" into "list the sections, fetch the one you need":
+The outline gives each section an index to fetch it by, and flags the ones
+large enough to be worth knowing about first:
 
 ```bash
-# List every heading, with the index to pass to --section
-readability guide cpp --outline
-
-# Only the top two levels, for a bird's eye view of a large guide
-readability guide cpp --outline --depth 2
-
-# Print one section: its heading and everything nested under it
-readability guide shell --section "Function Comments"
-readability guide cpp --section 10.4
-
-# Sections can be saved like whole guides can
-readability guide python --section "Imports" --output imports.md
+$ readability guide cpp
+Google C++ Style Guide
+  1  Background
+    1.1  Goals of the Style Guide
+  2  C++ Version
+  3  Header Files  (1.7k words)
+    3.1  Self-contained Headers
+    ...
+# 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.
+
 A section reference can be any of the following:
 
 | Reference | Example |
 |-----------|---------|
-| Section index, as shown by `--outline` | `--section 2.2.4` |
-| Heading text, case-insensitive, or its slug | `--section "function comments"` |
-| A parent-scoped path, spaces around the `>` | `--section "Imports > Decision"` |
+| 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.
@@ -187,28 +235,50 @@ printed section number or the heading text over a positional index, since
 positional indices shift when an unnumbered guide is re-synced.
 
 A reference that matches several headings is reported rather than guessed at,
-listing the index and path of every candidate on stderr:
+listing every candidate on stderr:
 
 ```bash
-$ readability guide python --section Decision
+$ readability guide python Decision
 Error: 'Decision' matches 19 headings in the 'python' guide. Repeat with one of:
-  --section 2.1.4 (Python Language Rules > Lint > Decision)
-  --section 2.2.4 (Python Language Rules > Imports > Decision)
+  2.1.4 (Python Language Rules > Lint > Decision)
+  2.2.4 (Python Language Rules > Imports > Decision)
   ...
 ```
 
-Content goes to stdout and diagnostics to stderr, so both flags are safe to
+### When a Reference Misses
+
+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:
+
+```bash
+$ readability guide python f-string
+Error: Found no heading matching 'f-string' in the 'python' guide.
+It appears in these sections:
+  3.10  Python Style Rules > Strings
+  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:
+
+```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.
 
 ### Supported Languages
 
-Use `readability languages` to see a full list of supported languages and
-their aliases. This command also indicates which guides are currently
-available in the local cache with a `[cached]` label:
+Run `readability guide` with no language for the full list and which guides
+are cached:
 
 ```bash
-$ readability languages
+$ readability guide
 Supported languages and their aliases:
   - r [cached]
   - c++, cpp [cached]
@@ -226,6 +296,16 @@ Supported languages and their aliases:
   - vim [cached]
 ```
 
+Refresh the cache with `sync`, which takes languages or refetches everything:
+
+```bash
+# Refetch one guide, or a few
+readability sync python shell
+
+# Refetch all of them
+readability sync
+```
+
 ### Offline Mode
 
 The tool stores local copies of the style guides in the `guides/` directory

{readability_cli-0.7.0 → readability_cli-0.8.0}/README.md

@@ -14,7 +14,8 @@ and quick access to style conventions without browsing HTML pages.
   Pyrefly are used automatically when a project does not define its own.
 - **Style Guides**: A `guide` command that fetches the latest Google style
   guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown,
-  navigable by outline and by section rather than read whole.
+  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.
 
@@ -26,8 +27,9 @@ You can run the tool directly without installing it using `uvx`:
 # Check and fix formatting for the current directory
 uvx --from readability-cli readability check . --fix
 
-# Get the Python style guide
+# Outline the Python style guide, then read one of its sections
 uvx --from readability-cli readability guide python
+uvx --from readability-cli readability guide python 2.2
 ```
 
 ## Installation
@@ -78,17 +80,58 @@ readability check . --fix
 
 ### Supported Tools
 
-| Tool | Supported Extensions | Trigger Files |
-|------|----------------------|---------------|
-| **Ruff** | `.py` | `pyproject.toml`, `ruff.toml`, `.ruff.toml` |
-| **Pyrefly** | `.py` | `pyproject.toml`, `pyrefly.toml` |
-| **Biome** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.jsonc`, `.css`, `.html` | `biome.json`, `biome.jsonc` |
-| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | `.prettierrc*`, `prettier.config.*` |
-| **gofmt** | `.go` | `go.mod` |
+| 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` | `biome.json` or `biome.jsonc` | `npx` |
+| **Prettier** | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.scss`, `.html`, `.md`, `.yml`, `.yaml` | `.prettierrc*` or `prettier.config.*` | `npx` |
+| **gofmt** | `.go` | `go.mod` | — |
+
+**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.
+
+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.
+
+Set `UV_OFFLINE=1` to forbid fetching. A tool that then cannot be reached
+fails the run rather than passing it.
+
+Ruff and Pyrefly ship with bundled configurations, so they run on any file
+they handle without the project arranging anything. Biome, Prettier and gofmt
+bring no defaults here, so they wait until the project asks with a config
+file.
+
+A tool that could not be reached at all is never skipped quietly:
 
-The command will only run a tool if its trigger file exists in the current
-working directory and the tool is available in your `PATH`. For `biome` and
-`prettier`, it attempts to run them via `npx`.
+```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).
+
+# 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.
+
+`check` exits non-zero on findings and on having verified nothing, so it can
+gate CI without a clean exit ever meaning "the tools were absent".
 
 ### Default Configurations
 
@@ -102,59 +145,64 @@ project-level configuration takes full precedence over the bundled defaults.
 
 ## Style Guides
 
-The `guide` command prints a Google style guide as Markdown, using the local
-cache when available:
+The `guide` command reads a Google style guide, using the local cache when
+available. It has four forms:
 
 ```bash
-# Get the Python style guide (uses local cache if available)
-readability guide python
-
-# Force fetching the latest version from the web
-readability guide python --remote
+# Which languages have a guide, and which are cached
+readability guide
 
-# Save a style guide to a file
-readability guide cpp --output cpp-style.md
+# The outline of one: every heading, a few KB where the guide is 200
+readability guide python
 
-# Search a guide without printing it: the pipe carries it, you see matches
-readability guide python | grep -n "f-string"
+# One section, by index, heading text, or a parent-scoped path
+readability guide cpp 10.4
+readability guide shell "Function Comments"
+readability guide python "Imports > Decision"
 
-# Synchronize all supported style guides to the local cache
-readability sync
+# The whole guide, for grepping or when you really do want all of it
+readability guide cpp --full
+readability guide python --full | grep -i f-string
 ```
 
-A guide can exceed 100 KB, so printing one whole is rarely what you want.
-`--outline` and `--section` below cover navigating to a rule; piping to
-`grep` covers finding wording that no heading names. Neither leaves a copy
-behind, which is what a coding agent should do rather than redirecting a
-guide into the repository it is working on.
+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.
+
+`REF` and `--full` cannot be combined; that is refused rather than resolved
+by a precedence rule you would have to know.
 
 ### Navigating a Guide
 
-`--outline` lists a guide's headings and `--section` prints just one of them,
-which turns "read 200 KB" into "list the sections, fetch the one you need":
+The outline gives each section an index to fetch it by, and flags the ones
+large enough to be worth knowing about first:
 
 ```bash
-# List every heading, with the index to pass to --section
-readability guide cpp --outline
-
-# Only the top two levels, for a bird's eye view of a large guide
-readability guide cpp --outline --depth 2
-
-# Print one section: its heading and everything nested under it
-readability guide shell --section "Function Comments"
-readability guide cpp --section 10.4
-
-# Sections can be saved like whole guides can
-readability guide python --section "Imports" --output imports.md
+$ readability guide cpp
+Google C++ Style Guide
+  1  Background
+    1.1  Goals of the Style Guide
+  2  C++ Version
+  3  Header Files  (1.7k words)
+    3.1  Self-contained Headers
+    ...
+# 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.
+
 A section reference can be any of the following:
 
 | Reference | Example |
 |-----------|---------|
-| Section index, as shown by `--outline` | `--section 2.2.4` |
-| Heading text, case-insensitive, or its slug | `--section "function comments"` |
-| A parent-scoped path, spaces around the `>` | `--section "Imports > Decision"` |
+| 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.
@@ -173,28 +221,50 @@ printed section number or the heading text over a positional index, since
 positional indices shift when an unnumbered guide is re-synced.
 
 A reference that matches several headings is reported rather than guessed at,
-listing the index and path of every candidate on stderr:
+listing every candidate on stderr:
 
 ```bash
-$ readability guide python --section Decision
+$ readability guide python Decision
 Error: 'Decision' matches 19 headings in the 'python' guide. Repeat with one of:
-  --section 2.1.4 (Python Language Rules > Lint > Decision)
-  --section 2.2.4 (Python Language Rules > Imports > Decision)
+  2.1.4 (Python Language Rules > Lint > Decision)
+  2.2.4 (Python Language Rules > Imports > Decision)
   ...
 ```
 
-Content goes to stdout and diagnostics to stderr, so both flags are safe to
+### When a Reference Misses
+
+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:
+
+```bash
+$ readability guide python f-string
+Error: Found no heading matching 'f-string' in the 'python' guide.
+It appears in these sections:
+  3.10  Python Style Rules > Strings
+  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:
+
+```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.
 
 ### Supported Languages
 
-Use `readability languages` to see a full list of supported languages and
-their aliases. This command also indicates which guides are currently
-available in the local cache with a `[cached]` label:
+Run `readability guide` with no language for the full list and which guides
+are cached:
 
 ```bash
-$ readability languages
+$ readability guide
 Supported languages and their aliases:
   - r [cached]
   - c++, cpp [cached]
@@ -212,6 +282,16 @@ Supported languages and their aliases:
   - vim [cached]
 ```
 
+Refresh the cache with `sync`, which takes languages or refetches everything:
+
+```bash
+# Refetch one guide, or a few
+readability sync python shell
+
+# Refetch all of them
+readability sync
+```
+
 ### Offline Mode
 
 The tool stores local copies of the style guides in the `guides/` directory

{readability_cli-0.7.0 → readability_cli-0.8.0}/guides/cppguide.md

@@ -415,7 +415,7 @@ brackets:
   and `<string>`).
 * POSIX, Linux, and Windows system headers (e.g., `<unistd.h>`
   and `<windows.h>`).
-* In rare cases, third\_party libraries (e.g., `<Python.h>`).
+* In rare cases, third_party libraries (e.g., `<Python.h>`).
 
 In `dir/foo.cc` or
 `dir/foo_test.cc`, whose main
@@ -1005,7 +1005,7 @@ Dynamic initialization of static local variables is allowed (and common).
   it by using a function-local static pointer or reference (e.g.,
   `static const auto& impl = *new T(args...);`).
 
-### thread\_local Variables
+### thread_local Variables
 
 `thread_local` variables that aren't declared inside a function
 must be initialized with a true compile-time constant,
@@ -3989,7 +3989,7 @@ the rules are the rules.
 For the purposes of the naming rules below, a "word" is anything that you
 would write in English without internal spaces. Either words are all lowercase,
 with underscores between words
-("[snake\_case](https://en.wikipedia.org/wiki/Snake_case)"), or words
+("[snake_case](https://en.wikipedia.org/wiki/Snake_case)"), or words
 are mixed case with the first letter of each word capitalized
 ("[camelCase](https://en.wikipedia.org/wiki/Camel_case)" or
 "[PascalCase](https://en.wiktionary.org/wiki/Pascal_case)").

{readability_cli-0.7.0 → readability_cli-0.8.0}/guides/tsguide.md

@@ -110,8 +110,8 @@ There are four variants of import statements in ES6 and TypeScript:
 
 | Import type | Example | Use for |
 | --- | --- | --- |
-| module[module\_import] | `import * as foo from '...';` | TypeScript imports |
-| named[destructuring\_import] | `import {SomeThing} from '...';` | TypeScript imports |
+| module[module_import] | `import * as foo from '...';` | TypeScript imports |
+| named[destructuring_import] | `import {SomeThing} from '...';` | TypeScript imports |
 | default | `import SomeThing from '...';` | Only for other external code that requires them |
 | side-effect | `import '...';` | Only to import libraries for their side-effects on load (such as custom elements) |
 

{readability_cli-0.7.0 → readability_cli-0.8.0}/pyproject.toml

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