sarj-python-lint 0.33.0__tar.gz → 0.35.0__tar.gz

{sarj_python_lint-0.33.0 → sarj_python_lint-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.33.0
+Version: 0.35.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
 Project-URL: Repository, https://github.com/sarj-ai/standards
@@ -76,7 +76,7 @@ package inside your own project. Third-party privates are never flagged.
 
 **It replaces ruff's `PLC2701 import-private-name`,** whose only exemption is
 *same top-level package* — a different question, and one that cannot separate
-`from bulbul.stores.task_store import _row_to_task` (real; export it) from
+`from app.stores.order_store import _row_to_order` (real; export it) from
 `from livekit.agents.inference_runner import _InferenceRunner` (no fix exists).
 `sarj-lint-configs` ≥ 0.8.0 ships `PLC2701` in its ignore list for exactly this
 reason; if you take that config, turn this hook on, or you lose the check
@@ -100,7 +100,7 @@ each guard was built from are recorded in the rule module docstrings.
 ```
 
 `redundant-docstring` finds real volume on a codebase that has never had it
-(105 in noura-be), so the same baseline ratchet applies.
+(105 in one first-party repo), so the same baseline ratchet applies.
 
 ### Docstring-ceremony rules (0.31.0)
 
@@ -161,10 +161,11 @@ to WARNING — usually vanish in production while looking fine locally.
 The one legitimate reason to touch stdlib logging in a loguru house is to
 *bridge* it, and the bridge cannot be written without naming both loggers, so a
 module importing loguru is exempt. Measured across two production repos that
-exemption is exact: all four sites that import stdlib logging
-(`bulbul/__init__.py`, `bulbul/configure_logging.py`, `agent/main.py`,
-noura-be's `common/logging.py`) are bridges, all four import loguru, and no
-other module in either repo imports stdlib logging at all. Tests, `scripts/`,
+exemption is exact: all four sites that import stdlib logging (three in the
+first repo — its package `__init__.py`, a dedicated `configure_logging.py`, and
+a service entrypoint `main.py` — plus a `common/logging.py` in the second) are
+bridges, all four import loguru, and no other module in either repo imports
+stdlib logging at all. Tests, `scripts/`,
 `notebooks/`, generated files and `if TYPE_CHECKING:` imports are also exempt.
 
 **This is a house-convention rule, not a universal one.** A *library* should log
@@ -176,7 +177,8 @@ UUIDv4 keys scatter B-tree inserts across every leaf page, where `uuidv7()`
 (Postgres 18) is time-ordered and appends. It is the embedded-SQL third of a
 policy the stack already states twice — `ruff.strict.toml` bans `uuid.uuid4`,
 and `sarj-sql-lint`'s SARJ109 `prefer-uuidv7-default` covers `.sql` migration
-files (41 sites in bulbul, 14 in noura-be, all of them a primary-key `DEFAULT`).
+files (41 sites in one first-party repo, 14 in another, all of them a
+primary-key `DEFAULT`).
 A literal only counts when it is SQL-shaped, so prose naming the function is not
 a finding.
 
@@ -195,7 +197,7 @@ flagged — measured across five repos those are the entire population.
 The second test-quality wave. Where the 0.15.0 family asks "does this test assert
 anything?", this one asks "does it exercise anything real?" — it pushes suites off
 hand-rolled doubles and onto the real store, the real database and a maintained fake
-library. Measured against bulbul, noura-be, five other first-party repos and fourteen
+library. Measured against seven first-party repos and fourteen
 OSS corpora; two candidates were dropped outright when the corpus showed they only
 duplicated ruff.
 
@@ -203,7 +205,6 @@ duplicated ruff.
     - id: sarj-prefer-real-store-in-tests          # SARJ058
     - id: sarj-prefer-library-fake                 # SARJ059
     - id: sarj-tautological-mock-assertion         # SARJ060
-    - id: sarj-no-patching-system-under-test       # SARJ061
     - id: sarj-over-mocked-test                    # SARJ062
     - id: sarj-interaction-only-test               # SARJ063
     - id: sarj-trivially-true-assertion            # SARJ064
@@ -255,8 +256,8 @@ file falls back under the global cap, so an allowance cannot outlive its debt.
 pygrep hooks, not SARJ rules, and both need a `files:`/`exclude:` from the
 consumer. An AST port of each was built and measured, and the boundary each
 encodes turned out to be repo-specific rather than shared: "shared fake" flagged
-9/9 single-use test doubles in noura-be that are idiomatic where they sit, and
-"raw connection in a test" flagged 46 sites in bulbul of which every one is
+9/9 single-use test doubles in one first-party repo that are idiomatic where
+they sit, and "raw connection in a test" flagged 46 sites in another of which every one is
 already an intentional exemption (store tests asserting DB state, pool-lifecycle
 tests, retention tests where physical deletion is the subject). SARJ036
 `no-raw-sql-in-tests` remains the corpus-validated shared rule for raw SQL in
@@ -303,11 +304,11 @@ an omitted filter.
 
 Measured before shipping: **0 findings across 26,345 files** of pydantic, trio,
 attrs, Airflow and Home Assistant — single-tenant codebases have no tenant
-column, so the rule is silent by construction — and 0 in noura-be, ai, kpi-hub
-and demo-gateway. In bulbul it finds 10 sites, all genuine fail-open
+column, so the rule is silent by construction — and 0 across four other
+first-party repos. In the fifth it finds 10 sites, all genuine fail-open
 compositions, two of which were reachable cross-tenant reads at the time of
-writing (`POST /v1/calls/list` and `POST /v1/calls/batch/list`, both of which
-composed `WHERE 1=1` for a user whose `organization_id` was NULL).
+writing (two paginated list endpoints, both of which composed `WHERE 1=1` for a
+user whose `organization_id` was NULL).
 
 ### Assertions that can never fail (0.23.0)
 
@@ -343,7 +344,7 @@ ran* — as is anything inside a pytest-benchmark test.
 
 Measured before shipping: **4 findings across 28,608 files** — 26,346 of
 pydantic, trio, attrs, Airflow and Home Assistant plus 2,262 first-party files
-in bulbul, noura-be, kpi-hub, ai and demo-gateway. All 4 are true positives
+across five first-party repos. All 4 are true positives
 (Home Assistant `tests/helpers/test_device_registry.py:3711` and `:3777`,
 `tests/components/emulated_hue/test_hue_api.py:1078`, Airflow
 `providers/apache/hdfs/.../log/test_hdfs_task_handler.py:170`); 0 false

{sarj_python_lint-0.33.0 → sarj_python_lint-0.35.0}/README.md

@@ -58,7 +58,7 @@ package inside your own project. Third-party privates are never flagged.
 
 **It replaces ruff's `PLC2701 import-private-name`,** whose only exemption is
 *same top-level package* — a different question, and one that cannot separate
-`from bulbul.stores.task_store import _row_to_task` (real; export it) from
+`from app.stores.order_store import _row_to_order` (real; export it) from
 `from livekit.agents.inference_runner import _InferenceRunner` (no fix exists).
 `sarj-lint-configs` ≥ 0.8.0 ships `PLC2701` in its ignore list for exactly this
 reason; if you take that config, turn this hook on, or you lose the check
@@ -82,7 +82,7 @@ each guard was built from are recorded in the rule module docstrings.
 ```
 
 `redundant-docstring` finds real volume on a codebase that has never had it
-(105 in noura-be), so the same baseline ratchet applies.
+(105 in one first-party repo), so the same baseline ratchet applies.
 
 ### Docstring-ceremony rules (0.31.0)
 
@@ -143,10 +143,11 @@ to WARNING — usually vanish in production while looking fine locally.
 The one legitimate reason to touch stdlib logging in a loguru house is to
 *bridge* it, and the bridge cannot be written without naming both loggers, so a
 module importing loguru is exempt. Measured across two production repos that
-exemption is exact: all four sites that import stdlib logging
-(`bulbul/__init__.py`, `bulbul/configure_logging.py`, `agent/main.py`,
-noura-be's `common/logging.py`) are bridges, all four import loguru, and no
-other module in either repo imports stdlib logging at all. Tests, `scripts/`,
+exemption is exact: all four sites that import stdlib logging (three in the
+first repo — its package `__init__.py`, a dedicated `configure_logging.py`, and
+a service entrypoint `main.py` — plus a `common/logging.py` in the second) are
+bridges, all four import loguru, and no other module in either repo imports
+stdlib logging at all. Tests, `scripts/`,
 `notebooks/`, generated files and `if TYPE_CHECKING:` imports are also exempt.
 
 **This is a house-convention rule, not a universal one.** A *library* should log
@@ -158,7 +159,8 @@ UUIDv4 keys scatter B-tree inserts across every leaf page, where `uuidv7()`
 (Postgres 18) is time-ordered and appends. It is the embedded-SQL third of a
 policy the stack already states twice — `ruff.strict.toml` bans `uuid.uuid4`,
 and `sarj-sql-lint`'s SARJ109 `prefer-uuidv7-default` covers `.sql` migration
-files (41 sites in bulbul, 14 in noura-be, all of them a primary-key `DEFAULT`).
+files (41 sites in one first-party repo, 14 in another, all of them a
+primary-key `DEFAULT`).
 A literal only counts when it is SQL-shaped, so prose naming the function is not
 a finding.
 
@@ -177,7 +179,7 @@ flagged — measured across five repos those are the entire population.
 The second test-quality wave. Where the 0.15.0 family asks "does this test assert
 anything?", this one asks "does it exercise anything real?" — it pushes suites off
 hand-rolled doubles and onto the real store, the real database and a maintained fake
-library. Measured against bulbul, noura-be, five other first-party repos and fourteen
+library. Measured against seven first-party repos and fourteen
 OSS corpora; two candidates were dropped outright when the corpus showed they only
 duplicated ruff.
 
@@ -185,7 +187,6 @@ duplicated ruff.
     - id: sarj-prefer-real-store-in-tests          # SARJ058
     - id: sarj-prefer-library-fake                 # SARJ059
     - id: sarj-tautological-mock-assertion         # SARJ060
-    - id: sarj-no-patching-system-under-test       # SARJ061
     - id: sarj-over-mocked-test                    # SARJ062
     - id: sarj-interaction-only-test               # SARJ063
     - id: sarj-trivially-true-assertion            # SARJ064
@@ -237,8 +238,8 @@ file falls back under the global cap, so an allowance cannot outlive its debt.
 pygrep hooks, not SARJ rules, and both need a `files:`/`exclude:` from the
 consumer. An AST port of each was built and measured, and the boundary each
 encodes turned out to be repo-specific rather than shared: "shared fake" flagged
-9/9 single-use test doubles in noura-be that are idiomatic where they sit, and
-"raw connection in a test" flagged 46 sites in bulbul of which every one is
+9/9 single-use test doubles in one first-party repo that are idiomatic where
+they sit, and "raw connection in a test" flagged 46 sites in another of which every one is
 already an intentional exemption (store tests asserting DB state, pool-lifecycle
 tests, retention tests where physical deletion is the subject). SARJ036
 `no-raw-sql-in-tests` remains the corpus-validated shared rule for raw SQL in
@@ -285,11 +286,11 @@ an omitted filter.
 
 Measured before shipping: **0 findings across 26,345 files** of pydantic, trio,
 attrs, Airflow and Home Assistant — single-tenant codebases have no tenant
-column, so the rule is silent by construction — and 0 in noura-be, ai, kpi-hub
-and demo-gateway. In bulbul it finds 10 sites, all genuine fail-open
+column, so the rule is silent by construction — and 0 across four other
+first-party repos. In the fifth it finds 10 sites, all genuine fail-open
 compositions, two of which were reachable cross-tenant reads at the time of
-writing (`POST /v1/calls/list` and `POST /v1/calls/batch/list`, both of which
-composed `WHERE 1=1` for a user whose `organization_id` was NULL).
+writing (two paginated list endpoints, both of which composed `WHERE 1=1` for a
+user whose `organization_id` was NULL).
 
 ### Assertions that can never fail (0.23.0)
 
@@ -325,7 +326,7 @@ ran* — as is anything inside a pytest-benchmark test.
 
 Measured before shipping: **4 findings across 28,608 files** — 26,346 of
 pydantic, trio, attrs, Airflow and Home Assistant plus 2,262 first-party files
-in bulbul, noura-be, kpi-hub, ai and demo-gateway. All 4 are true positives
+across five first-party repos. All 4 are true positives
 (Home Assistant `tests/helpers/test_device_registry.py:3711` and `:3777`,
 `tests/components/emulated_hue/test_hue_api.py:1078`, Airflow
 `providers/apache/hdfs/.../log/test_hdfs_task_handler.py:170`); 0 false

{sarj_python_lint-0.33.0 → sarj_python_lint-0.35.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.33.0"
+version = "0.35.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]

{sarj_python_lint-0.33.0 → sarj_python_lint-0.35.0}/src/sarj_python_lint/__main__.py

@@ -84,6 +84,9 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
 class _Args(argparse.Namespace):
     cmd: str | None
     rule: list[str]
+    # `explain` takes exactly one rule, so it cannot share `--rule`'s list slot
+    # without widening the type and losing the check on every `check` call site.
+    which: str
     files: list[Path]
     baseline: Path | None
     update_baseline: Path | None
@@ -92,11 +95,33 @@ class _Args(argparse.Namespace):
         super().__init__()
         self.cmd = None
         self.rule = []
+        self.which = ""
         self.files = []
         self.baseline = None
         self.update_baseline = None
 
 
+def _explain(wanted: str) -> int:
+    """Print a rule's summary plus the derived links to its examples and evidence.
+
+    This is the runtime consumer of the one-line module docstring: it is what
+    makes an inaccurate summary visible rather than merely unread.
+
+    """
+    key = wanted.strip()
+    cls = REGISTRY.get(key) or next((c for c in REGISTRY.values() if c.code.upper() == key.upper()), None)
+    if cls is None:
+        sys.stderr.write(f"unknown rule: {wanted}\navailable: {', '.join(sorted(REGISTRY))}\n")
+        return 2
+    summary = (sys.modules[cls.__module__].__doc__ or "").strip().splitlines()
+    sys.stdout.write(
+        f"{cls.code}  {cls.id}\n{summary[0] if summary else cls.description}\nexamples: {cls.examples_url()}\n"
+    )
+    if cls.has_evidence:
+        sys.stdout.write(f"evidence: {cls.evidence_url()}\n")
+    return 0
+
+
 def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
     counts: dict[str, dict[str, int]] = {}
     for d in diags:
@@ -112,9 +137,6 @@ def _read_baseline(path: Path) -> dict[str, dict[str, int]]:
     asserted — a hand-edited baseline should degrade to "not baselined" rather
     than crash the run or silently suppress on a malformed entry.
 
-    Returns:
-        The baseline counts, with any entry of the wrong shape dropped.
-
     """
     raw: object = json.loads(  # pyright: ignore[reportAny] — json.loads is an untyped stdlib boundary; the shape is narrowed below
         path.read_text(encoding="utf-8")
@@ -134,12 +156,7 @@ def _read_baseline(path: Path) -> dict[str, dict[str, int]]:
 
 
 def _apply_baseline(diags: list[Diagnostic], baseline: dict[str, dict[str, int]]) -> list[Diagnostic]:
-    """Suppress up to the baselined count per (path, code); excess diags survive.
-
-    Returns:
-        The diagnostics that exceed the baselined count for their (path, code).
-
-    """
+    """Suppress up to the baselined count per (path, code); excess diags survive."""
     seen: Counter[tuple[str, str]] = Counter()
     out: list[Diagnostic] = []
     for d in diags:
@@ -179,6 +196,9 @@ def main(argv: list[str] | None = None) -> int:
 
     sub.add_parser("list-rules", help="List available rule IDs.")
 
+    explain_p = sub.add_parser("explain", help="Print one rule's summary and the links to its examples and evidence.")
+    explain_p.add_argument("which", metavar="rule", help="Rule ID or SARJ code.")
+
     args = parser.parse_args(argv, namespace=_Args())
 
     if args.cmd == "list-rules":
@@ -187,6 +207,9 @@ def main(argv: list[str] | None = None) -> int:
             sys.stdout.write(f"{inst.code:8}  {rid:40}  {inst.description}\n")
         return 0
 
+    if args.cmd == "explain":
+        return _explain(args.which)
+
     diags = _check(args.rule, args.files)
     if args.update_baseline is not None:
         args.update_baseline.write_text(json.dumps(_baseline_counts(diags), indent=2, sort_keys=True) + "\n")

{sarj_python_lint-0.33.0 → sarj_python_lint-0.35.0}/src/sarj_python_lint/_ratchet_cli.py

@@ -49,12 +49,7 @@ class _Args(argparse.Namespace):
 
 
 def _build_parser() -> argparse.ArgumentParser:
-    """Assemble the argument parser.
-
-    Returns:
-        The configured parser.
-
-    """
+    """Assemble the argument parser."""
     parser = argparse.ArgumentParser(
         prog="sarj-ratchet",
         description=(
@@ -99,12 +94,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: list[str] | None = None) -> int:
-    """Run the ratchet.
-
-    Returns:
-        0 when every ceiling holds (or the baseline was re-seeded), 1 otherwise.
-
-    """
+    """Run the ratchet."""
     args = _build_parser().parse_args(argv, namespace=_Args())
     root = args.root.resolve()
     baseline_path = args.baseline if args.baseline is not None else root / _DEFAULT_BASELINE_NAME
@@ -162,12 +152,7 @@ def _update(
     *,
     allow_increase: bool,
 ) -> int:
-    """Re-seed the baseline, refusing raises unless they were explicitly reviewed.
-
-    Returns:
-        0 when the baseline was written, 1 when the re-seed was refused.
-
-    """
+    """Re-seed the baseline, refusing raises unless they were explicitly reviewed."""
     would_raise = gate(measurement, baseline)
     if would_raise and not allow_increase:
         sys.stderr.write("REFUSED: --update would raise ceilings; pass --allow-increase if this was reviewed:\n")

{sarj_python_lint-0.33.0 → sarj_python_lint-0.35.0}/src/sarj_python_lint/_secret_names.py

@@ -130,9 +130,6 @@ def identifier_tokens(identifier: str) -> list[str]:
     mixed-case single word like `ToKeN` (which camel-splitting shreds into
     `to`/`ke`/`n`) still surfaces its intended `token` form.
 
-    Returns:
-        The ordered lowercase tokens decomposed from `identifier`.
-
     """
     tokens: list[str] = []
     for segment in _SEGMENT_RE.split(identifier):
@@ -152,10 +149,6 @@ def leading_word(identifier: str) -> str | None:
     useless `hassecret` rather than `has`. Splitting the leading segment with the
     same camel regex makes `has_secret` and `hasSecret` both yield `has`.
 
-    Returns:
-        The lowercased leading word, or None when `identifier` has no word
-        characters at all.
-
     """
     for segment in _SEGMENT_RE.split(identifier):
         if not segment:
@@ -166,12 +159,7 @@ def leading_word(identifier: str) -> str | None:
 
 
 def is_secret_name(identifier: str) -> bool:
-    """Report whether `identifier` names raw secret material (a credential, not metadata).
-
-    Returns:
-        True when `identifier` denotes a credential rather than metadata.
-
-    """
+    """Report whether `identifier` names raw secret material (a credential, not metadata)."""
     tokens = identifier_tokens(identifier)
     if tokens and tokens[-1] in _INNOCUOUS_WORDS:
         return False
@@ -183,10 +171,5 @@ def is_secret_name(identifier: str) -> bool:
 
 
 def _has_api_key(tokens: list[str]) -> bool:
-    """Report whether `api` is immediately followed by `key` (the split form of `api_key`).
-
-    Returns:
-        True when an `api` token is directly followed by a `key` token.
-
-    """
+    """Report whether `api` is immediately followed by `key` (the split form of `api_key`)."""
     return any(a == "api" and b == "key" for a, b in pairwise(tokens))

sarj_python_lint-0.35.0/src/sarj_python_lint/_version.py

@@ -0,0 +1,9 @@
+"""Resolve the installed package version, with a source-tree fallback."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("sarj-python-lint")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

{sarj_python_lint-0.33.0 → sarj_python_lint-0.35.0}/src/sarj_python_lint/ratchet.py

@@ -94,12 +94,7 @@ class Measurement:
 
     @property
     def total(self) -> int:
-        """Total suppressions counted.
-
-        Returns:
-            The sum over every code key.
-
-        """
+        """Total suppressions counted."""
         return sum(self.codes.values())
 
 
@@ -123,12 +118,7 @@ class Failure:
     actual: int
 
     def format(self) -> str:
-        """Render the failure with the remediation for its dimension.
-
-        Returns:
-            A multi-sentence message naming the key, both numbers and the fix.
-
-        """
+        """Render the failure with the remediation for its dimension."""
         head = f"FAIL[{self.dimension}] {self.key}: {self.actual} suppressions, ceiling {self.ceiling}."
         return f"{head} {_REMEDIATION[self.dimension]}"
 
@@ -164,9 +154,6 @@ def measure(
     contributes 0 rather than raising, so a baseline outliving a rename fails
     loudly on the package's disappearance rather than crashing.
 
-    Returns:
-        The measurement.
-
     """
     codes: Counter[str] = Counter()
     package_counts: Counter[str] = Counter()
@@ -189,12 +176,7 @@ def measure(
 
 
 def count_source(source: str) -> Counter[str]:
-    """Count the suppressions in one file's text, keyed by dialect and code.
-
-    Returns:
-        The per-key counts for this file.
-
-    """
+    """Count the suppressions in one file's text, keyed by dialect and code."""
     counts: Counter[str] = Counter()
     for line in source.splitlines():
         _count_line(line, counts)
@@ -202,13 +184,7 @@ def count_source(source: str) -> Counter[str]:
 
 
 def gate(measurement: Measurement, baseline: Baseline) -> list[Failure]:
-    """Compare a measurement against the baseline's three ceilings.
-
-    Returns:
-        Every exceeded ceiling, ordered code → package → file, each dimension
-        sorted by key so output is stable across runs.
-
-    """
+    """Compare a measurement against the baseline's three ceilings."""
     failures = [
         Failure(dimension="code", key=key, ceiling=c, actual=n)
         for key, n in sorted(measurement.codes.items())
@@ -228,13 +204,7 @@ def gate(measurement: Measurement, baseline: Baseline) -> list[Failure]:
 
 
 def improvements(measurement: Measurement, baseline: Baseline) -> dict[str, tuple[int, int]]:
-    """Find the code keys now below their ceiling — the wins worth locking in.
-
-    Returns:
-        `{key: (ceiling, actual)}` for every code that shrank, including codes
-        that reached zero and are no longer present at all.
-
-    """
+    """Find the code keys now below their ceiling — the wins worth locking in."""
     out: dict[str, tuple[int, int]] = {}
     for key, ceiling in baseline.codes.items():
         actual = measurement.codes.get(key, 0)
@@ -250,9 +220,6 @@ def seed(measurement: Measurement, baseline: Baseline) -> Baseline:
     that dropped to or below the global ceiling loses its exception, so the
     allowance cannot outlive the debt it was granted for.
 
-    Returns:
-        The re-seeded baseline.
-
     """
     exceptions = {path: n for path, n in measurement.files.items() if n > baseline.per_file_ceiling}
     return Baseline(
@@ -269,9 +236,6 @@ def load_baseline(path: Path) -> Baseline:
     A hand-edited baseline degrades to "not baselined" (ceiling 0) for the
     malformed entry rather than crashing the gate or silently passing.
 
-    Returns:
-        The parsed baseline.
-
     """
     raw: object = json.loads(  # pyright: ignore[reportAny] — json.loads is an untyped stdlib boundary; every read below narrows
         path.read_text(encoding="utf-8")
@@ -289,24 +253,14 @@ def load_baseline(path: Path) -> Baseline:
 
 
 def _get(mapping: object, key: str) -> object:
-    """Read one key out of a value that may or may not be a JSON object.
-
-    Returns:
-        The value at `key`, or None when `mapping` is not an object or lacks it.
-
-    """
+    """Read one key out of a value that may or may not be a JSON object."""
     if not isinstance(mapping, dict):
         return None
     return mapping.get(key)  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] — json leaves are Any
 
 
 def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
-    """Render a baseline as the JSON text to write.
-
-    Returns:
-        The serialized baseline, newline-terminated.
-
-    """
+    """Render a baseline as the JSON text to write."""
     payload = {
         "_comment": (
             "Suppression ceilings, written by `sarj-ratchet --update`. Counts may "
@@ -332,9 +286,6 @@ def discover_packages(root: Path, excluded_dir_names: frozenset[str] = DEFAULT_E
     Used when neither `--package` nor a baseline names the packages, so the
     first run needs no configuration.
 
-    Returns:
-        The package names, sorted.
-
     """
     return sorted(
         name
@@ -347,12 +298,7 @@ def discover_packages(root: Path, excluded_dir_names: frozenset[str] = DEFAULT_E
 
 
 def _int_map(value: object) -> dict[str, int]:
-    """Narrow a JSON value to `{str: int}`, dropping anything else.
-
-    Returns:
-        The well-formed entries only.
-
-    """
+    """Narrow a JSON value to `{str: int}`, dropping anything else."""
     if not isinstance(value, dict):
         return {}
     return {
@@ -363,12 +309,7 @@ def _int_map(value: object) -> dict[str, int]:
 
 
 def _python_files(root: Path, excluded_dir_names: frozenset[str]) -> Iterator[Path]:
-    """Yield every `.py` file under `root`, skipping excluded directories.
-
-    Yields:
-        Each Python file path.
-
-    """
+    """Yield every `.py` file under `root`, skipping excluded directories."""
     if not root.is_dir():
         return
     for path in sorted(root.rglob("*.py")):
@@ -377,12 +318,7 @@ def _python_files(root: Path, excluded_dir_names: frozenset[str]) -> Iterator[Pa
 
 
 def _read(path: Path) -> str:
-    """Read a source file, treating undecodable bytes as empty.
-
-    Returns:
-        The file text, or `""` when it cannot be decoded.
-
-    """
+    """Read a source file, treating undecodable bytes as empty."""
     try:
         return path.read_text(encoding="utf-8")
     except UnicodeDecodeError, OSError: