sarj-python-lint 0.80.3__tar.gz → 0.80.5__tar.gz

{sarj_python_lint-0.80.3 → sarj_python_lint-0.80.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.80.3
+Version: 0.80.5
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
-Requires-Dist: ruff>=0.16.3
+Requires-Dist: ruff>=0.16.5
 Description-Content-Type: text/markdown
 
 <!-- Generated by `code-standards maintain docs sync`; do not edit. -->

{sarj_python_lint-0.80.3 → sarj_python_lint-0.80.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.80.3"
+version = "0.80.5"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["ruff>=0.16.3"]
+dependencies = ["ruff>=0.16.5"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"
@@ -31,7 +31,7 @@ Issues = "https://github.com/sarj-ai/code-standards/issues"
 [dependency-groups]
 dev = [
   "pytest>=9.1.1",
-  "ruff>=0.16.3",
+  "ruff>=0.16.5",
   "basedpyright>=1.39.10",
 ]
 

{sarj_python_lint-0.80.3 → sarj_python_lint-0.80.5}/src/sarj_python_lint/_ratchet_cli.py

@@ -155,6 +155,13 @@ def _ruff_selector_aliases() -> dict[str, str]:
             raise TypeError(msg)
         code = raw_item.get("code")
         name = raw_item.get("name")
+        if code is None and isinstance(name, str):
+            # Ruff accepts the name as the stable selector until it allocates
+            # a code, so preserve that suppression identity rather than
+            # rejecting a valid Ruff directive.
+            canonical = name.lower()
+            aliases[canonical] = canonical
+            continue
         if not isinstance(code, str) or not isinstance(name, str):
             msg = "Ruff rule catalog entry lacks a string code or name"
             raise TypeError(msg)

{sarj_python_lint-0.80.3 → sarj_python_lint-0.80.5}/src/sarj_python_lint/rules/_registry.py

@@ -10,6 +10,7 @@ from sarj_python_lint.rules.docstring_args_restate_signature import (
 from sarj_python_lint.rules.docstring_returns_restate_signature import (
     DocstringReturnsRestateSignature,
 )
+from sarj_python_lint.rules.excessive_commentary import ExcessiveCommentary
 from sarj_python_lint.rules.fakes_in_shared_location import FakesInSharedLocation
 from sarj_python_lint.rules.fastapi_explicit_openapi_contract import FastapiExplicitOpenapiContract
 from sarj_python_lint.rules.iac_source_coupled_test import IacSourceCoupledTest
@@ -152,6 +153,7 @@ from sarj_python_lint.rules.store_insert_requires_on_conflict import (
 from sarj_python_lint.rules.timestamp_order_requires_tiebreaker import TimestampOrderRequiresTiebreaker
 from sarj_python_lint.rules.trailing_value_narration import TrailingValueNarration
 from sarj_python_lint.rules.trivially_true_assertion import TriviallyTrueAssertion
+from sarj_python_lint.rules.typed_error_reasons import TypedErrorReasons
 from sarj_python_lint.rules.uncontrolled_randomness_in_test import UncontrolledRandomnessInTest
 from sarj_python_lint.rules.unused_mock_setup import UnusedMockSetup
 
@@ -163,6 +165,7 @@ if TYPE_CHECKING:
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        ExcessiveCommentary.id: ExcessiveCommentary,
         PreferWalrusAwaitedNoneGuard.id: PreferWalrusAwaitedNoneGuard,
         TimestampOrderRequiresTiebreaker.id: TimestampOrderRequiresTiebreaker,
         NoStringConcatInLoop.id: NoStringConcatInLoop,
@@ -260,6 +263,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RequirePydanticOrdinalLowerBound.id: RequirePydanticOrdinalLowerBound,
         RequireNoDecodeForSplittingSettingsField.id: RequireNoDecodeForSplittingSettingsField,
         NoVagueSuppressionDescription.id: NoVagueSuppressionDescription,
+        TypedErrorReasons.id: TypedErrorReasons,
     }
 )
 

sarj_python_lint-0.80.5/src/sarj_python_lint/rules/excessive_commentary.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+import re
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    parse_or_none,
+)
+from sarj_python_lint.rules._prose_budget import (
+    groups,
+    has_technical_anchor,
+)
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_MIN_LINES = 4
+_MIN_WORDS = 28
+_RATIONALE_RE = re.compile(
+    r"\b(?:because|otherwise|therefore|must|never|cannot|can't|required?|invariant|"
+    r"compatibility|security|race|atomic|deadlock|rollback|lock|data loss)\b",
+    re.IGNORECASE,
+)
+_RATIONALE_SO_RE = re.compile(r"\bso\s+(?:that|a|an|the|this|it|we|they)\b", re.IGNORECASE)
+_BULLET_RE = re.compile(r"^\s*(?:[-*+] |\d+[.)] )", re.MULTILINE)
+_ACCUMULATOR_METHODS = frozenset({"add", "append", "extend", "update"})
+_MIN_ACCUMULATOR_CALLS = 2
+
+
+@final
+class ExcessiveCommentary(Rule):
+    id = "excessive-commentary"
+    code = "SARJ434"
+    documentation = RuleDocumentation(
+        summary="Long standalone implementation commentary — make the code self-documenting and retain only durable constraints.",
+        rationale=(
+            "A paragraph that narrates nearby implementation behavior competes with the code and can drift independently "
+            "from it."
+        ),
+        remediation=(
+            "Delete the narration and clarify names, types, or structure. Keep concise comments that record a durable "
+            "constraint or externally owned contract."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only contiguous standalone line-comment blocks with at least four non-empty lines and 28 words are inspected.",
+            "The paragraph must immediately precede an empty local collection that is then populated by at least two consecutive accumulator calls.",
+            "Generated files, directives, licenses, structured lists, docstrings, inline comments, rationale markers, and concrete technical anchors are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="activation-narration",
+                title="Implementation paragraph narrates a validation helper",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app.py",
+                        "def activation_reasons():\n"
+                        "    # Everything standing between this integration and being usable.\n"
+                        "    # Returns all the reasons rather than the first failure.\n"
+                        "    # Someone activating a half-built integration wants the complete list.\n"
+                        "    # That avoids discovering one problem per round trip.\n"
+                        "    reasons = []\n"
+                        "    reasons.extend(integration_reasons())\n"
+                        "    reasons.extend(endpoint_reasons())\n"
+                        "    return reasons\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="durable-constraint",
+                title="A concrete compatibility constraint remains local",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app.py",
+                        "# Legacy clients send `execution_phase` until API-812 is retired.\n"
+                        "# Keep the adapter at this boundary so internal models stay camelCase.\n"
+                        'phase = payload["execution_phase"]\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        accumulator_lines = _narrated_accumulator_lines(tree)
+        findings: list[Diagnostic] = []
+        for group in groups(path, source):
+            lines = tuple(stripped for line in group.text.splitlines() if (stripped := line.strip()))
+            if group.kind != "comment" or len(lines) < _MIN_LINES or len(group.text.split()) < _MIN_WORDS:
+                continue
+            comment_end_line = group.line + len(group.text.splitlines()) - 1
+            if comment_end_line + 1 not in accumulator_lines:
+                continue
+            if any(
+                (
+                    _BULLET_RE.search(group.text),
+                    has_technical_anchor(group.text),
+                    _RATIONALE_RE.search(group.text),
+                    _RATIONALE_SO_RE.search(group.text),
+                )
+            ):
+                continue
+            findings.append(
+                Diagnostic(
+                    path,
+                    group.line,
+                    group.col,
+                    self.code,
+                    self.description,
+                    column_encoding=group.column_encoding,
+                )
+            )
+        return findings
+
+
+def _narrated_accumulator_lines(tree: ast.Module) -> set[int]:
+    lines: set[int] = set()
+    for function in ast.walk(tree):
+        if not isinstance(function, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        _collect_accumulators(function.body, lines)
+    return lines
+
+
+def _collect_accumulators(statements: list[ast.stmt], lines: set[int]) -> None:
+    for index, statement in enumerate(statements):
+        name = _empty_collection_name(statement)
+        if name is not None:
+            mutations = 0
+            for following in statements[index + 1 :]:
+                if not _is_accumulator_call(following, name):
+                    break
+                mutations += 1
+            if mutations >= _MIN_ACCUMULATOR_CALLS:
+                lines.add(statement.lineno)
+        for child_statements in _nested_statement_lists(statement):
+            _collect_accumulators(child_statements, lines)
+
+
+def _empty_collection_name(statement: ast.stmt) -> str | None:
+    target: ast.expr | None = None
+    value: ast.expr | None = None
+    if isinstance(statement, ast.AnnAssign):
+        target, value = statement.target, statement.value
+    elif isinstance(statement, ast.Assign) and len(statement.targets) == 1:
+        target, value = statement.targets[0], statement.value
+    if not isinstance(target, ast.Name) or value is None:
+        return None
+    if isinstance(value, (ast.List, ast.Set)) and not value.elts:
+        return target.id
+    if isinstance(value, ast.Dict) and not value.keys:
+        return target.id
+    if (
+        isinstance(value, ast.Call)
+        and isinstance(value.func, ast.Name)
+        and value.func.id in {"dict", "list", "set"}
+        and not value.args
+        and not value.keywords
+    ):
+        return target.id
+    return None
+
+
+def _is_accumulator_call(statement: ast.stmt, name: str) -> bool:
+    if not isinstance(statement, ast.Expr) or not isinstance(statement.value, ast.Call):
+        return False
+    function = statement.value.func
+    return (
+        isinstance(function, ast.Attribute)
+        and function.attr in _ACCUMULATOR_METHODS
+        and isinstance(function.value, ast.Name)
+        and function.value.id == name
+    )
+
+
+def _nested_statement_lists(statement: ast.stmt) -> list[list[ast.stmt]]:
+    match statement:
+        case ast.For() | ast.AsyncFor() | ast.While() | ast.If():
+            return [statement.body, statement.orelse]
+        case ast.With() | ast.AsyncWith():
+            return [statement.body]
+        case ast.Try() | ast.TryStar():
+            return [
+                statement.body,
+                statement.orelse,
+                statement.finalbody,
+                *(handler.body for handler in statement.handlers),
+            ]
+        case ast.Match():
+            return [case.body for case in statement.cases]
+        case _:
+            return []

sarj_python_lint-0.80.5/src/sarj_python_lint/rules/typed_error_reasons.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, TypeGuard, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    parse_or_none,
+)
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+
+_ERROR_SUFFIXES = ("Error", "Exception")
+
+
+@final
+class TypedErrorReasons(Rule):
+    id = "typed-error-reasons"
+    code = "SARJ435"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Exception aggregates presentation strings instead of typed error reasons.",
+        rationale=(
+            "A collection of rendered sentences has no stable identity for API clients, UI formatting, telemetry, "
+            "or exhaustive handling; consumers must display or parse text that should be presentation-only."
+        ),
+        remediation=(
+            "Replace `list[str]` with a nominal reason type: usually a record containing a `StrEnum` code and typed "
+            "context. Format that structure only at the presentation boundary."
+        ),
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only an Error/Exception subclass whose direct Error/Exception base is visible in the class declaration is checked.",
+            "The constructor must have exactly one non-self parameter, annotated exactly `list[str]`, and join that same parameter inside `super().__init__(...)`.",
+            "Formatting delegated to another function, legacy `typing.List`, mixed constructor context, tests, and generated files are intentionally not inferred.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="rendered-reason-list",
+                title="An exception renders raw reason strings",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/errors.py",
+                        "class DomainError(Exception): ...\n\n"
+                        "class IncompleteError(DomainError):\n"
+                        "    def __init__(self, reasons: list[str]) -> None:\n"
+                        "        self.reasons = reasons\n"
+                        "        super().__init__(f\"Incomplete: {'; '.join(reasons)}\")\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/errors.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="typed-reason-list",
+                title="An exception carries nominal reason records",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/errors.py",
+                        "from dataclasses import dataclass\n"
+                        "from enum import StrEnum\n\n"
+                        "class ReasonCode(StrEnum):\n"
+                        "    MISSING_URL = 'missing_url'\n\n"
+                        "@dataclass(frozen=True)\n"
+                        "class Reason:\n"
+                        "    code: ReasonCode\n"
+                        "    field: str | None = None\n\n"
+                        "class DomainError(Exception): ...\n\n"
+                        "class IncompleteError(DomainError):\n"
+                        "    def __init__(self, reasons: list[Reason]) -> None:\n"
+                        "        self.reasons = reasons\n"
+                        "        super().__init__('Integration is incomplete')\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/errors.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if path.suffix != ".py" or is_test_path(path) or is_generated(path, source):
+            return []
+        if "list[str]" not in source or ".join(" not in source or "super(" not in source:
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+
+        diagnostics: list[Diagnostic] = []
+        for error_class in (node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)):
+            if not _is_conventional_exception(error_class):
+                continue
+            constructor = next(
+                (
+                    member
+                    for member in error_class.body
+                    if isinstance(member, ast.FunctionDef) and member.name == "__init__"
+                ),
+                None,
+            )
+            if constructor is None:
+                continue
+            parameter = _sole_string_list_parameter(constructor)
+            if parameter is None:
+                continue
+            joined = _joined_in_super_message(constructor, parameter.arg)
+            if joined is None:
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=path,
+                    line=joined.lineno,
+                    col=joined.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message=(
+                        f"`{error_class.name}` joins `{parameter.arg}: list[str]` into its message; carry nominal "
+                        "reason codes with typed context and format them at the presentation boundary"
+                    ),
+                )
+            )
+        return sorted(diagnostics, key=lambda diagnostic: (diagnostic.line, diagnostic.col))
+
+
+def _is_conventional_exception(node: ast.ClassDef) -> bool:
+    return node.name.endswith(_ERROR_SUFFIXES) and any(_tail(base).endswith(_ERROR_SUFFIXES) for base in node.bases)
+
+
+def _tail(node: ast.expr) -> str:
+    match node:
+        case ast.Name(id=name) | ast.Attribute(attr=name):
+            return name
+        case _:
+            return ""
+
+
+def _sole_string_list_parameter(function: ast.FunctionDef) -> ast.arg | None:
+    parameters = [
+        argument
+        for argument in (
+            *function.args.posonlyargs,
+            *function.args.args,
+            *function.args.kwonlyargs,
+        )
+        if argument.arg not in {"self", "cls"}
+    ]
+    if len(parameters) != 1:
+        return None
+    parameter = parameters[0]
+    return parameter if _is_string_list(parameter.annotation) else None
+
+
+def _is_string_list(annotation: ast.expr | None) -> bool:
+    return (
+        isinstance(annotation, ast.Subscript)
+        and isinstance(annotation.value, ast.Name)
+        and annotation.value.id == "list"
+        and isinstance(annotation.slice, ast.Name)
+        and annotation.slice.id == "str"
+    )
+
+
+def _joined_in_super_message(function: ast.FunctionDef, parameter: str) -> ast.Call | None:
+    for node in _own_scope_nodes(function):
+        if not _is_super_init_call(node):
+            continue
+        for argument in node.args:
+            joined = next(
+                (candidate for candidate in ast.walk(argument) if _joins_parameter(candidate, parameter)),
+                None,
+            )
+            if joined is not None:
+                return joined
+    return None
+
+
+def _own_scope_nodes(function: ast.FunctionDef) -> Iterator[ast.AST]:
+    stack: list[ast.AST] = list(function.body)
+    while stack:
+        node = stack.pop()
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)):
+            continue
+        yield node
+        stack.extend(ast.iter_child_nodes(node))
+
+
+def _is_super_init_call(node: ast.AST) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "__init__"
+        and isinstance(node.func.value, ast.Call)
+        and isinstance(node.func.value.func, ast.Name)
+        and node.func.value.func.id == "super"
+    )
+
+
+def _joins_parameter(node: ast.AST, parameter: str) -> TypeGuard[ast.Call]:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "join"
+        and len(node.args) == 1
+        and not node.keywords
+        and isinstance(node.args[0], ast.Name)
+        and node.args[0].id == parameter
+    )