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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.9.0
+Version: 0.10.1
 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,15 +168,21 @@ 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
 
 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, one import per line sorted as isort's
+`google` profile does, 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. Project `biome.json` and
 `biome.jsonc` files replace those bundled defaults for Biome-owned formats.
@@ -189,6 +195,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.1}/README.md

@@ -154,15 +154,21 @@ 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
 
 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, one import per line sorted as isort's
+`google` profile does, 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. Project `biome.json` and
 `biome.jsonc` files replace those bundled defaults for Biome-owned formats.
@@ -175,6 +181,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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.9.0"
+version = "0.10.1"
 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"
@@ -47,6 +47,12 @@ ignore = ["PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR2004"]
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
+[tool.ruff.lint.isort]
+force-single-line = true
+force-sort-within-sections = true
+single-line-exclusions = ["typing"]
+order-by-type = false
+
 [tool.ruff.lint.per-file-ignores]
 "test_*.py" = ["D"]
 "*_test.py" = ["D"]

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

@@ -1,20 +1,19 @@
 """Run readability checks and report their coverage."""
 
+from collections.abc import Sequence
 import dataclasses
 import logging
-import subprocess
-from collections.abc import Sequence
 from pathlib import Path
+import subprocess
 
 import click
 
-from readability.tools import (
-    ToolPlan,
-    _command_batches,
-    _get_tool_definitions,
-    _should_run_tool,
-    _tool_is_installed,
-)
+from readability.tools import _command_batches
+from readability.tools import _get_tool_definitions
+from readability.tools import _repository_root
+from readability.tools import _should_run_tool
+from readability.tools import _tool_is_installed
+from readability.tools import ToolPlan
 
 logger = logging.getLogger("readability")
 DEFAULT_TIMEOUT = 60
@@ -74,8 +73,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 +86,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 +100,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 +108,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 +127,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 +168,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 +217,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 +235,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.1}/readability/cli.py

@@ -1,21 +1,20 @@
 """Command-line interface for readability."""
 
+from collections.abc import Sequence
 import logging
 import os
 import sys
-from collections.abc import Sequence
 
 import click
 
 from readability.checking import check_paths
-from readability.guide import (
-    LANGUAGE_MAP,
-    get_guide,
-    get_guides_dir,
-    get_local_path,
-    refresh_guide,
-)
-from readability.outline import _echo_outline, _select_section
+from readability.guide import get_guide
+from readability.guide import get_guides_dir
+from readability.guide import get_local_path
+from readability.guide import LANGUAGE_MAP
+from readability.guide import refresh_guide
+from readability.outline import _echo_outline
+from readability.outline import _select_section
 
 logger = logging.getLogger("readability")
 
@@ -60,8 +59,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 +104,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 +187,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 +196,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 +209,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 +226,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 +237,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",

{readability_cli-0.9.0 → readability_cli-0.10.1}/readability/configs/ruff.toml

@@ -14,6 +14,14 @@ ignore = ["PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR2004"]
 [lint.pydocstyle]
 convention = "google"
 
+[lint.isort]
+# Mirrors isort's google profile; its lexicographical and group-by-package
+# options have no ruff equivalent
+force-single-line = true
+force-sort-within-sections = true
+single-line-exclusions = ["typing"]
+order-by-type = false
+
 [lint.per-file-ignores]
 # Docstring requirements are noise in test files
 "test_*.py" = ["D"]

{readability_cli-0.9.0 → readability_cli-0.10.1}/readability/guide.py

@@ -1,14 +1,15 @@
 """Fetch and cache Google style guides."""
 
+from importlib.resources import files
 import logging
 import os
 import warnings
-from importlib.resources import files
 
+from bs4 import BeautifulSoup
+from bs4 import XMLParsedAsHTMLWarning
 import click
-import requests
-from bs4 import BeautifulSoup, XMLParsedAsHTMLWarning
 from markdownify import markdownify as md
+import requests
 
 warnings.filterwarnings("ignore", category=XMLParsedAsHTMLWarning)
 
@@ -55,10 +56,7 @@ LANGUAGE_MAP = {
 
 BASE_URL = "https://google.github.io/styleguide/"
 
-# Style guides are dense with snake_case and dunder identifiers, and escaping
-# their underscores leaves 'from \_\_future\_\_ import' in the text a caller
-# greps or reads. CommonMark would render a bare '__future__' as emphasis, but
-# these guides are consumed as plain text, where fidelity matters more.
+# Escaping underscores would leave 'from \_\_future\_\_ import' in the text
 MARKDOWNIFY_OPTIONS = {"heading_style": "ATX", "escape_underscores": False}
 
 

{readability_cli-0.9.0 → readability_cli-0.10.1}/readability/outline.py

@@ -1,31 +1,27 @@
 """Parse, search, and render style-guide outlines."""
 
+from collections.abc import Iterator
+from collections.abc import Sequence
+from dataclasses import dataclass
 import re
 import sys
-from collections.abc import Iterator, Sequence
-from dataclasses import dataclass
 from typing import Any
 
 import click
 
-# A fence opens or closes a code block; anything inside is sample code, not
-# document structure. Guides for `#`-commented languages (shell, Python) would
-# otherwise report hundreds of code comments as headings.
+# Inside a fence is sample code, where a '#' comment is not a heading
 FENCE_PATTERN = re.compile(r"^\s{0,3}(?:```|~~~)")
 
-# Closing hashes are optional in ATX headings and must be space-separated, so
-# a title such as 'C#' keeps its trailing character.
+# Closing hashes are space-separated, so a title like 'C#' keeps its own
 HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.*?)(?:\s+#+)?\s*$")
 
-# A section number the document itself prints, e.g. '2.2' in '2.2 Imports'.
+# A number the document prints itself, e.g. '2.2' in '2.2 Imports'
 DOCUMENT_NUMBER_PATTERN = re.compile(r"^(\d+(?:\.\d+)*)\.?\s+(.+)$")
 
-# Guides put a heading's link targets on the lines above it, which would
-# otherwise trail the end of the preceding section.
+# Link targets sit above their heading, not at the end of the one before
 ANCHOR_PATTERN = re.compile(r'^<a id="[^"]*"></a>$')
 
-# The separator in a scoped reference such as 'Imports > Decision'. Spaces on
-# both sides are required so that a heading like '`Array<T>` Type' stays whole.
+# Scoped reference separator; spaces required so '`Array<T>` Type' stays whole
 PATH_SEPARATOR_PATTERN = re.compile(r"\s+>\s+")
 
 
@@ -148,8 +144,7 @@ def parse_headings(content: str) -> list[Heading]:
     if not raw:
         return []
 
-    # Only three of the shipped guides number their headings. A dotted number
-    # ('2.2') is the reliable signal; a bare leading digit is not.
+    # A dotted number is the reliable signal; a bare leading digit is not
     document_numbers = [
         match.group(1)
         for _, _, text in raw
@@ -157,8 +152,7 @@ def parse_headings(content: str) -> list[Heading]:
     ]
     numbered = any("." in number for number in document_numbers)
 
-    # A lone top-level heading is the document title: it roots the tree rather
-    # than being the first section, so numbering starts with its children.
+    # A lone top-level heading is the title, so numbering starts below it
     top_level = min(level for _, level, _ in raw)
     top_level_lines = [line for line, level, _ in raw if level == top_level]
     title_line = top_level_lines[0] if len(top_level_lines) == 1 else None
@@ -169,12 +163,7 @@ def parse_headings(content: str) -> list[Heading]:
         index = "" if line == title_line else _next_index(open_headings, level)
         number, title = _split_document_number(text, numbered)
 
-        # A guide that numbers its own sections is the authority on what they
-        # are called, so its numbers address them. A positional index would
-        # drift wherever the guide skips one — pyguide has no 2.15 at all,
-        # and calling its 2.16 by that name would cite a section that does
-        # not exist. The tree still advances above, so headings the guide
-        # leaves unnumbered keep a positional index to be reachable by.
+        # A guide's own numbers address its sections; an index would drift
         if number:
             index = number
         headings.append(
@@ -203,10 +192,7 @@ def _slugify(text: str) -> str:
     return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
 
 
-# Sections this long are worth warning about before one is fetched. Measured
-# over the shipped corpus, it marks the 4% that are expensive while leaving
-# the rest unannotated: a size on every line would read '0' on 59% of them,
-# which is noise in the one output whose job is to be scanned quickly.
+# Marks the expensive 4% of the corpus; a size on every line would be noise
 LARGE_SECTION_WORDS = 1200
 
 
@@ -263,8 +249,7 @@ def format_outline(headings: Sequence[Heading], content: str = "") -> str:
             section = extract_section(content, headings, position)
             size = _format_size(len(section.split()))
 
-        # The index already carries the guide's own number where it has one,
-        # so printing the heading verbatim would show it twice.
+        # The index already carries the guide's number where it has one
         lines.append(f"{indent}{prefix}{heading.title}{size}")
 
     return "\n".join(lines)
@@ -281,8 +266,7 @@ def _matches_component(heading: Heading, component: str, exact: bool) -> bool:
     Returns:
         True if the component identifies the heading.
     """
-    # Numbers are only ever compared in full; a substring of a number would
-    # match unrelated sections.
+    # Numbers compare in full; a substring would match unrelated sections
     wanted = component.strip().rstrip(".")
     if wanted and wanted in {heading.index, heading.number}:
         return True
@@ -369,8 +353,7 @@ def find_headings(headings: Sequence[Heading], reference: str) -> list[int]:
     if not components:
         return []
 
-    # Prefer whole matches; fall back to substrings only when nothing matches
-    # in full, so 'Imports' does not also select 'Imports and Exports'.
+    # Whole matches first, so 'Imports' does not select 'Imports and Exports'
     for exact in (True, False):
         matches = [
             position
@@ -512,9 +495,7 @@ def find_mentions(
 
     lines = content.splitlines()
 
-    # Only an indexed heading can be offered. The document title has no index
-    # because it is the whole guide rather than a section within it, so
-    # crediting the preamble to it would suggest reading everything.
+    # The title has no index, so crediting it would suggest reading everything
     sections = [
         (position, _section_bounds(lines, headings, position))
         for position in range(len(headings))
@@ -526,10 +507,7 @@ def find_mentions(
         if needle not in line.lower():
             continue
 
-        # Bounds nest, so the last section still covering the line is the
-        # innermost one that prints it. A section sheds the anchors of the
-        # heading below it, and those fall to an ancestor rather than to the
-        # section they merely trail.
+        # Bounds nest, so the last one covering a line is what prints it
         holders = [
             position
             for position, (start, end) in sections
@@ -577,8 +555,7 @@ def _echo_outline(content: str, language: str) -> None:
     example = _example_reference(headings)
     if example:
         count = sum(1 for heading in headings if heading.index)
-        # stdout is block-buffered when redirected, so without this the hint
-        # lands above the outline it is meant to follow
+        # Redirected stdout is block-buffered, so the hint would land first
         sys.stdout.flush()
         click.echo(
             f"# {count} sections · print one:  "
@@ -656,8 +633,7 @@ def _select_section(content: str, reference: str, language: str) -> str:
     if not matches:
         _report_no_heading(content, headings, reference, language)
 
-    # Reporting every candidate beats returning the first one silently, since
-    # guides repeat headings ('Decision' appears under every Python rule).
+    # Guides repeat headings, so name every candidate rather than guess
     if len(matches) > 1:
         click.echo(
             f"Error: '{reference}' matches {len(matches)} headings in the "