sarj-python-lint 1.66.3__tar.gz → 1.68.0__tar.gz

{sarj_python_lint-1.66.3 → sarj_python_lint-1.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.66.3
+Version: 1.68.0
 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/

{sarj_python_lint-1.66.3 → sarj_python_lint-1.68.0}/pyproject.toml

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

sarj_python_lint-1.68.0/src/sarj_python_lint/rules/_declared_contracts.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._project_index import ProjectIndexSet, SourceUnit, SymbolRef
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+MODEL_BASES = frozenset({"pydantic.BaseModel", "pydantic.main.BaseModel"})
+SETTINGS_BASES = frozenset({"pydantic_settings.BaseSettings", "pydantic_settings.main.BaseSettings"})
+_MAX_DEPTH = 8
+_TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
+
+
+@dataclass(frozen=True)
+class DeclaredClass:
+    unit: SourceUnit
+    declaration: ast.ClassDef
+
+
+def _class_metadata_annotation(annotation: ast.expr, semantics: AnnotationSemantics) -> bool:
+    pending = [annotation]
+    seen: set[str] = set()
+    while pending:
+        node = semantics.parse(pending.pop())
+        if node is None:
+            return True
+        for member in ast.walk(node):
+            if isinstance(member, ast.Subscript) and semantics.imports.resolved_symbol(
+                member.value, sources=_TYPING_SOURCES
+            ) in {"ClassVar", "Final"}:
+                return True
+            if isinstance(member, ast.Name) and member.id in semantics.aliases and member.id not in seen:
+                seen.add(member.id)
+                pending.append(semantics.aliases[member.id])
+    return False
+
+
+class DeclaredContracts:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+        self._field_cache: dict[ast.ClassDef, dict[str, ast.AnnAssign]] = {}
+        self._module_annotations: dict[Path, AnnotationSemantics] = {}
+        self.project = context.session.project or ProjectIndexSet.single(context.path, context.source)
+        self.unit = self.project.unit(context.path)
+        if self.unit is not None and self.unit.tree is not context.tree:
+            self.unit = SourceUnit(self.unit.path, self.unit.module, self.unit.source, context.tree, self.unit.imports)
+            self.project = self.project.with_unit(self.unit)
+        if self.unit is not None and self.unit.module is None:
+            self.unit = SourceUnit(
+                context.path,
+                "__snippet__",
+                context.source,
+                context.tree,
+                {
+                    name: SymbolRef(target.module, target.symbol or "")
+                    for name, target in context.module_imports.bindings.items()
+                },
+            )
+            self.project = self.project.with_unit(self.unit)
+
+    def class_type(
+        self, expression: ast.expr, unit: SourceUnit | None = None, *, at: ast.AST | None = None
+    ) -> DeclaredClass | None:
+        owner = unit or self.unit
+        if owner is None or not self._lookup_allowed(expression, owner, at):
+            return None
+        summary = self.project.class_for(owner, expression)
+        source = self.project.source_unit(summary.symbol.module) if summary is not None else None
+        if source is None or source.tree is None or summary is None:
+            return None
+        declaration = self._stable_declaration(source, summary.symbol.name)
+        return DeclaredClass(source, declaration) if declaration is not None else None
+
+    def _lookup_allowed(self, expression: ast.expr, owner: SourceUnit, at: ast.AST | None) -> bool:
+        if owner is not self.unit or (at or expression) not in self.context.parents:
+            return True
+        root = expression
+        while isinstance(root, ast.Attribute):
+            root = root.value
+        if not isinstance(root, ast.Name):
+            return True
+        binding = self.context.static_resource_provenance.binding(root.id, at or expression)
+        return (
+            isinstance(binding, ast.alias | ast.ClassDef)
+            and root.id not in self.context.static_resource_provenance.mutated
+        )
+
+    def _stable_declaration(self, source: SourceUnit, name: str) -> ast.ClassDef | None:
+        if source.tree is None:
+            return None
+        declarations = [node for node in source.tree.body if isinstance(node, ast.ClassDef) and node.name == name]
+        if len(declarations) != 1 or declarations[0].keywords:
+            return None
+        if not self._identity_decorators(source, declarations[0]):
+            return None
+        if any(
+            isinstance(node, ast.Name) and node.id == name and isinstance(node.ctx, ast.Store | ast.Del)
+            for statement in source.tree.body
+            if not isinstance(statement, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef)
+            for node in ast.walk(statement)
+        ):
+            return None
+        return declarations[0]
+
+    def _identity_decorators(self, source: SourceUnit, declaration: ast.ClassDef) -> bool:
+        if not declaration.decorator_list:
+            return True
+        if source.tree is None:
+            return False
+        imports = (
+            self.context.module_imports
+            if source.path == self.context.path
+            else ImportIndex.from_tree(source.tree, module_scope_only=True)
+        )
+        return all(
+            imports.resolves(decorator, sources=_TYPING_SOURCES, symbol="final")
+            for decorator in declaration.decorator_list
+        )
+
+    def inherits(self, model: DeclaredClass, bases: frozenset[str]) -> bool:
+        return self.project.class_inherits_from(model.unit, model.declaration.name, bases)
+
+    def model_fields(self, model: DeclaredClass) -> dict[str, ast.AnnAssign]:
+        if model.unit.tree is None:
+            return {}
+        cached = self._field_cache.get(model.declaration)
+        if cached is not None:
+            return cached
+        semantics = self._module_semantics(model.unit)
+        fields = {
+            node.target.id: node
+            for node in model.declaration.body
+            if isinstance(node, ast.AnnAssign)
+            and isinstance(node.target, ast.Name)
+            and not node.target.id.startswith("_")
+            and node.target.id != "model_config"
+            and not _class_metadata_annotation(node.annotation, semantics)
+        }
+        self._field_cache[model.declaration] = fields
+        return fields
+
+    def _module_semantics(self, unit: SourceUnit) -> AnnotationSemantics:
+        if unit.tree is None:
+            return self.context.annotation_semantics
+        semantics = self._module_annotations.get(unit.path)
+        if semantics is None:
+            imports = (
+                self.context.module_imports
+                if unit.path == self.context.path
+                else ImportIndex.from_tree(unit.tree, module_scope_only=True)
+            )
+            semantics = AnnotationSemantics.from_imports(unit.tree, imports)
+            self._module_annotations[unit.path] = semantics
+        return semantics
+
+    def annotation(self, expression: ast.expr, unit: SourceUnit | None = None) -> DeclaredClass | None:
+        semantics = self.context.annotation_semantics
+        if unit is not None and unit is not self.unit and unit.tree is not None:
+            semantics = self._module_semantics(unit)
+        candidates = [
+            model
+            for member in semantics.transparent_members(expression)
+            if (model := self.class_type(member, unit, at=expression)) is not None
+        ]
+        return candidates[0] if len(candidates) == 1 else None
+
+    def value(self, expression: ast.expr, *, depth: int = 0) -> DeclaredClass | None:
+        if depth > _MAX_DEPTH:
+            return None
+        match expression:
+            case ast.Await():
+                return self.value(expression.value, depth=depth + 1)
+            case ast.Name():
+                return self._local_value(expression, depth)
+            case ast.Call():
+                return self.class_type(expression.func) or self._call_result(expression, depth)
+            case _:
+                return None
+
+    def _local_value(self, expression: ast.Name, depth: int) -> DeclaredClass | None:
+        binding = self.context.static_resource_provenance.binding(expression.id, expression)
+        if isinstance(binding, ast.arg) and binding.annotation is not None:
+            return self.annotation(binding.annotation)
+        parent = self.context.parents.get(binding) if binding is not None else None
+        if isinstance(parent, ast.AnnAssign):
+            return self.annotation(parent.annotation)
+        if isinstance(binding, ast.Name):
+            value = self.context.static_resource_provenance.assignment_value(binding, expression)
+            return self.value(value, depth=depth + 1) if value is not None else None
+        return None
+
+    def _call_result(self, expression: ast.Call, depth: int) -> DeclaredClass | None:
+        match expression.func:
+            case ast.Name():
+                binding = self.context.static_resource_provenance.binding(expression.func.id, expression)
+                if isinstance(binding, ast.FunctionDef | ast.AsyncFunctionDef) and binding.returns is not None:
+                    return self.annotation(binding.returns)
+                return None
+            case ast.Attribute():
+                return self._method_result(expression.func, depth)
+            case _:
+                return None
+
+    def _method_result(self, target: ast.Attribute, depth: int) -> DeclaredClass | None:
+        model = self.class_type(target.value) or self.value(target.value, depth=depth + 1)
+        if model is None:
+            return None
+        if target.attr in {"model_validate", "model_validate_json", "model_copy"} and self.inherits(
+            model, MODEL_BASES | SETTINGS_BASES
+        ):
+            return model
+        methods = [
+            node
+            for node in model.declaration.body
+            if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) and node.name == target.attr
+        ]
+        if len(methods) == 1 and methods[0].returns is not None and not methods[0].decorator_list:
+            return self.annotation(methods[0].returns, model.unit)
+        return None
+
+
+def ordinary_pytest_test(function: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext) -> bool:
+    if not function.name.startswith("test_"):
+        return False
+    owner = context.parents.get(function)
+    if isinstance(owner, ast.ClassDef) and (owner.bases or owner.decorator_list or owner.keywords):
+        return False
+    for decorator in function.decorator_list:
+        target = decorator.func if isinstance(decorator, ast.Call) else decorator
+        qualified = context.imports.resolved_qualified_name(target)
+        if qualified is None or not qualified.startswith("pytest.mark."):
+            return False
+    return True

{sarj_python_lint-1.66.3 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/_registry.py

@@ -219,6 +219,7 @@ if TYPE_CHECKING:
 from sarj_python_lint.rules.delete_route_returns_no_content import DeleteRouteReturnsNoContent
 from sarj_python_lint.rules.duplicate_adjacent_exception_handler import DuplicateAdjacentExceptionHandler
 from sarj_python_lint.rules.duplicate_closed_pure_helper import DuplicateClosedPureHelper
+from sarj_python_lint.rules.duplicate_pytest_fixture_params import DuplicatePytestFixtureParams
 from sarj_python_lint.rules.no_conflicting_pydantic_alias_validation import NoConflictingPydanticAliasValidation
 from sarj_python_lint.rules.no_contradictory_type_guard import NoContradictoryTypeGuard
 from sarj_python_lint.rules.no_create_verb_in_post_path import NoCreateVerbInPostPath
@@ -236,8 +237,14 @@ from sarj_python_lint.rules.no_slash_collection_root_under_prefix import NoSlash
 from sarj_python_lint.rules.no_unknown_pydantic_validator_field import NoUnknownPydanticValidatorField
 from sarj_python_lint.rules.no_work_verb_get_route import NoWorkVerbGetRoute
 from sarj_python_lint.rules.prefer_bulk_upsert import PreferBulkUpsert
+from sarj_python_lint.rules.prefer_direct_import_module import PreferDirectImportModule
 from sarj_python_lint.rules.prefer_discriminated_model_union import PreferDiscriminatedModelUnion
+from sarj_python_lint.rules.prefer_precise_object_contract import PreferPreciseObjectContract
 from sarj_python_lint.rules.prefer_psycopg_executemany import PreferPsycopgExecutemany
+from sarj_python_lint.rules.prefer_pydantic_model_assertion import PreferPydanticModelAssertion
+from sarj_python_lint.rules.prefer_pytest_dependency_fixtures import PreferPytestDependencyFixtures
+from sarj_python_lint.rules.prefer_typed_settings_field import PreferTypedSettingsField
+from sarj_python_lint.rules.pytest_fixture_returns_closed_resource import PytestFixtureReturnsClosedResource
 from sarj_python_lint.rules.redundant_test_constructor_forwarder import RedundantTestConstructorForwarder
 from sarj_python_lint.rules.repeated_unimplemented_test_contract import RepeatedUnimplementedTestContract
 from sarj_python_lint.rules.require_exp_on_jwt_decode import RequireExpOnJwtDecode
@@ -247,6 +254,13 @@ from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOr
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        PytestFixtureReturnsClosedResource.id: PytestFixtureReturnsClosedResource,
+        DuplicatePytestFixtureParams.id: DuplicatePytestFixtureParams,
+        PreferTypedSettingsField.id: PreferTypedSettingsField,
+        PreferDirectImportModule.id: PreferDirectImportModule,
+        PreferPreciseObjectContract.id: PreferPreciseObjectContract,
+        PreferPydanticModelAssertion.id: PreferPydanticModelAssertion,
+        PreferPytestDependencyFixtures.id: PreferPytestDependencyFixtures,
         PreferBulkUpsert.id: PreferBulkUpsert,
         PreferPsycopgExecutemany.id: PreferPsycopgExecutemany,
         StoreFieldUpdateReusesUpsert.id: StoreFieldUpdateReusesUpsert,

{sarj_python_lint-1.66.3 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/_resource_provenance.py

@@ -31,6 +31,10 @@ _SCOPES = (
 )
 _RESOURCE_OWNERS = MappingProxyType(
     {
+        "builtins": frozenset({"open"}),
+        "io": frozenset({"open", "StringIO", "BytesIO"}),
+        "tempfile": frozenset({"TemporaryFile", "NamedTemporaryFile"}),
+        "httpx": frozenset({"Client", "AsyncClient"}),
         "asyncio": frozenset({"sleep", "CancelledError", "exceptions.CancelledError"}),
         "contextlib": frozenset({"ExitStack", "AsyncExitStack", "_BaseExitStack"}),
         "subprocess": frozenset({"Popen", "TimeoutExpired"}),

{sarj_python_lint-1.66.3 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/_test_composition.py

@@ -65,7 +65,13 @@ def _class_owner(
     return unit, owner
 
 
-def constructor(context: PythonFileContext, expression: ast.expr, project: ProjectIndexSet) -> Constructor | None:
+def constructor(
+    context: PythonFileContext,
+    expression: ast.expr,
+    project: ProjectIndexSet,
+    *,
+    minimum_collaborators: int = _MIN_COLLABORATORS,
+) -> Constructor | None:
     resolved = _class_owner(context, expression, project)
     if resolved is None:
         return None
@@ -87,7 +93,7 @@ def constructor(context: PythonFileContext, expression: ast.expr, project: Proje
         and _is_port(project, unit, parameter.annotation)
         and stored.get(parameter.arg) in invoked
     )
-    if len(collaborators) < _MIN_COLLABORATORS:
+    if len(collaborators) < minimum_collaborators:
         return None
     return Constructor(
         SymbolRef(unit.module, owner.name),

sarj_python_lint-1.68.0/src/sarj_python_lint/rules/duplicate_pytest_fixture_params.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._ast_index import walk as walk_ast
+from sarj_python_lint.rules._paths import is_test_path
+from sarj_python_lint.rules.pytest_fixture_returns_bare_tuple import fixture_declarations
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules.pytest_fixture_returns_bare_tuple import FixtureDeclaration
+
+
+_BAD = 'import pytest\n\n@pytest.fixture(params=("empty", "empty"))\ndef payload(request):\n    return request.param\n'
+
+
+@final
+class DuplicatePytestFixtureParams(Rule):
+    id: str = "duplicate-pytest-fixture-params"
+    code: str = "SARJ524"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Review repeated immutable values in a pytest fixture parameter list.",
+        rationale=(
+            "Each fixture parameter reruns its dependent tests. Repeating the same immutable literal can add "
+            "execution time without exercising a distinct input; Ruff PT014 covers test parametrization, not fixture params."
+        ),
+        remediation=(
+            "Review the dependent test contracts, then remove an accidental duplicate. Preserve intentional repetition "
+            "with explicit case IDs or an exact SARJ524 suppression explaining the repeated-run contract."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only directly imported pytest/pytest-asyncio fixtures in test paths with one decorator and literal list/tuple params are analyzed.",
+            "Compares immutable scalar/tuple literals with type and floating-point sign preserved; mutable values, calls, aliases and pytest.param metadata are not compared.",
+            "Explicit IDs, decorator unpacking and fixtures using request beyond direct request.param loads are excluded.",
+            "Dependent fixtures, hooks and tests may observe case indices, generated IDs or repeated execution; findings require contract review and are never auto-deleted.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="repeated-fixture-input",
+                title="The same input schedules the dependent tests twice",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("tests/conftest.py", _BAD),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="distinct-fixture-inputs",
+                title="Each fixture parameter represents a distinct input",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("tests/conftest.py", _BAD.replace('"empty", "empty"', '"empty", "filled"')),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if (
+            not is_test_path(context.path)
+            or context.generated
+            or "params" not in context.symbol_source
+            or context.tree is None
+        ):
+            return []
+        findings: list[Diagnostic] = []
+        for fixture in fixture_declarations(context.tree):
+            params = _parameter_values(fixture, context)
+            if params is None:
+                continue
+            first_values: dict[str, ast.expr] = {}
+            for value in params.elts:
+                key = _literal_key(value)
+                if key is None:
+                    continue
+                first = first_values.setdefault(key, value)
+                if first is value or is_suppressed(context.source_lines, value.lineno, self.code):
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=value.lineno,
+                        col=value.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=(
+                            f"fixture `{fixture.name}` repeats the immutable parameter from line {first.lineno}; "
+                            "review dependent contracts before removing it, or give intentional repetition explicit IDs"
+                        ),
+                    )
+                )
+        return findings
+
+
+def _parameter_values(fixture: FixtureDeclaration, context: PythonFileContext) -> ast.List | ast.Tuple | None:
+    decorator = fixture.decorator
+    if (
+        len(fixture.node.decorator_list) != 1
+        or not isinstance(decorator, ast.Call)
+        or decorator.args
+        or any(keyword.arg is None for keyword in decorator.keywords)
+        or _observes_request_identity(fixture.node, context)
+    ):
+        return None
+    keywords = {keyword.arg: keyword.value for keyword in decorator.keywords}
+    if len(keywords) != len(decorator.keywords):
+        return None
+    ids = keywords.get("ids")
+    if ids is not None and not (isinstance(ids, ast.Constant) and ids.value is None):
+        return None
+    params = keywords.get("params")
+    return params if isinstance(params, ast.List | ast.Tuple) else None
+
+
+def _literal_key(value: ast.expr) -> str | None:
+    if isinstance(value, ast.Constant) and isinstance(value.value, str | bytes | bool | int | float | type(None)):
+        return _scalar_key(value=value.value)
+    if (
+        isinstance(value, ast.UnaryOp)
+        and isinstance(value.op, ast.UAdd | ast.USub)
+        and isinstance(value.operand, ast.Constant)
+        and isinstance(value.operand.value, int | float)
+        and not isinstance(value.operand.value, bool)
+    ):
+        number = value.operand.value
+        number = -number if isinstance(value.op, ast.USub) else +number
+        return _scalar_key(value=number)
+    if isinstance(value, ast.Tuple):
+        keys = tuple(_literal_key(item) for item in value.elts)
+        if all(key is not None for key in keys):
+            return "tuple:" + "".join(f"{len(key)}:{key}" for key in keys if key is not None)
+    return None
+
+
+def _scalar_key(*, value: str | bytes | float | None) -> str:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return f"int:{value:x}"
+    return f"{type(value).__name__}:{value!r}"
+
+
+def _observes_request_identity(node: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext) -> bool:
+    for child in walk_ast(node):
+        if isinstance(child, ast.Name) and child.id == "request":
+            parent = context.parents.get(child)
+            if not (
+                isinstance(child.ctx, ast.Load)
+                and isinstance(parent, ast.Attribute)
+                and parent.value is child
+                and parent.attr == "param"
+                and isinstance(parent.ctx, ast.Load)
+            ):
+                return True
+    return False

{sarj_python_lint-1.66.3 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/excessive_commentary.py

@@ -14,8 +14,10 @@ from sarj_python_lint.rule_base import (
     RuleCategory,
     RuleDocumentation,
     RuleExample,
+    Severity,
 )
 from sarj_python_lint.rules._ast_index import walk as walk_ast
+from sarj_python_lint.rules._comments import has_external_reference
 from sarj_python_lint.rules._prose_budget import (
     groups,
     has_technical_anchor,
@@ -27,8 +29,10 @@ if TYPE_CHECKING:
     from sarj_python_lint.rules._ast_index import NodeIndex
 
 
-_MIN_LINES = 4
-_MIN_WORDS = 28
+_MIN_LINES = 3
+_MIN_WORDS = 20
+_ERROR_MIN_LINES = 4
+_ERROR_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",
@@ -45,21 +49,24 @@ 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.",
+        summary="Review long implementation comments; express behavior through code and keep constraints concise.",
         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."
+            "Make behavior clear through names, types, validators and cohesive functions. Shorten remaining explanation "
+            "to a concise constraint or protocol reference. Keep necessary detail with an explained exact-code "
+            "exception; never delete a required constraint or create abstraction solely to satisfy this warning."
         ),
         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.",
+            "Contiguous standalone implementation comment blocks with at least three non-empty lines and 20 words are inspected.",
+            "The paragraph must immediately precede executable implementation code; narrative comments in tests and module setup are included.",
+            "The previously shipped accumulator pattern remains an error; expanded implementation commentary is a warning requiring review, with no automatic deletion.",
+            "Rationale, technical vocabulary and external citations do not exempt a long paragraph from warning-level review. Their existing protection against accumulator errors remains intact.",
+            "Generated files, directives, licenses, structured lists, docstrings, inline comments and short constraints are excluded.",
         ),
         examples=(
             RuleExample(
@@ -111,24 +118,31 @@ class ExcessiveCommentary(Rule):
         tree = context.tree
         if tree is None:
             return []
+        implementation_lines = {
+            node.lineno
+            for node in context.nodes(ast.stmt)
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Import, ast.ImportFrom))
+        }
         accumulator_lines = _narrated_accumulator_lines(tree, node_index=context.node_index)
         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:
+            words = len(group.text.split())
+            if group.kind != "comment" or len(lines) < _MIN_LINES or words < _MIN_WORDS:
                 continue
             comment_end_line = group.line + len(group.text.splitlines()) - 1
-            if comment_end_line + 1 not in accumulator_lines:
+            if comment_end_line + 1 not in implementation_lines:
                 continue
-            if any(
+            if _BULLET_RE.search(group.text):
+                continue
+            review_only = any(
                 (
-                    _BULLET_RE.search(group.text),
                     has_technical_anchor(group.text),
+                    has_external_reference(group.text),
                     _RATIONALE_RE.search(group.text),
                     _RATIONALE_SO_RE.search(group.text),
                 )
-            ):
-                continue
+            )
             findings.append(
                 Diagnostic(
                     path,
@@ -136,6 +150,14 @@ class ExcessiveCommentary(Rule):
                     group.col,
                     self.code,
                     self.description,
+                    severity=(
+                        Severity.ERROR
+                        if not review_only
+                        and comment_end_line + 1 in accumulator_lines
+                        and len(lines) >= _ERROR_MIN_LINES
+                        and words >= _ERROR_MIN_WORDS
+                        else Severity.WARNING
+                    ),
                     column_encoding=group.column_encoding,
                 )
             )