sarj-python-lint 1.77.3__tar.gz → 1.81.0__tar.gz

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.77.3
+Version: 1.81.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/
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
 Requires-Dist: ruff>=0.17.2
-Requires-Dist: sarj-rule-contracts==0.4.1
+Requires-Dist: sarj-rule-contracts==0.4.2
 Requires-Dist: sqlglot==30.24.0
 Requires-Dist: typer==0.27.3
 Description-Content-Type: text/markdown

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.77.3"
+version = "1.81.0"
 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 = ["sarj-rule-contracts==0.4.1", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
+dependencies = ["sarj-rule-contracts==0.4.2", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/__main__.py

@@ -166,6 +166,7 @@ def analyze(
 
 _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
     {
+        "SARJ020": frozenset({"SARJ437"}),
         "SARJ054": frozenset({"SARJ419"}),
         "SARJ448": frozenset({"SARJ419"}),
         "SARJ523": frozenset({"SARJ419"}),
@@ -340,14 +341,9 @@ def _suppressed_diagnostics(
 
 def _suppressed_codes(codes: dict[str, set[Severity]]) -> set[tuple[str, Severity]]:
     suppressed = _precedence_suppressions(codes)
-    # SARJ094 is deliberately staged as a warning while teams calibrate the
-    # FastAPI contract policy. Its route-aware return finding still owns the
-    # overlapping annotation failure: emitting the blocking SARJ447 twin would
-    # defeat warning staging and give two remediations for one return contract.
+    # SARJ094 warning staging owns the overlapping return failure; its blocking twin would defeat that policy.
     if "SARJ094" in codes:
         suppressed.update(_route_contract_suppressions(codes))
-    # The promoted signature-restatement rules now block. Keep their errors and
-    # drop only the lower-severity typed-docstring twin at the same owner.
     if _typed_docstring_warning_is_superseded(codes):
         suppressed.add(("SARJ092", Severity.WARNING))
     return suppressed

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/_autofix.py

@@ -33,6 +33,7 @@ from sarj_python_lint.rule_base import Severity
 from sarj_python_lint.rules import (
     REGISTRY,
     duplicate_adjacent_exception_handler as exception_rule,
+    no_comment_cruft as comment_cruft_rule,
     prefer_collection_comprehension as collection_rule,
     prefer_or_pattern as pattern_rule,
 )
@@ -201,7 +202,11 @@ def _comment_fix(source: _Source, diagnostic: Diagnostic) -> list[TextEdit]:
     if token is None:
         return []
     body = token.string.removeprefix("#").strip()
-    if diagnostic.code == "SARJ016" and _SEPARATOR.fullmatch(body) is None:
+    if (
+        diagnostic.code == "SARJ016"
+        and _SEPARATOR.fullmatch(body) is None
+        and not comment_cruft_rule.is_section_label(body)
+    ):
         return []
     start = source.starts[token.start[0] - 1]
     if source.text[start : start + token.start[1]].strip():
@@ -1312,7 +1317,7 @@ _BUILDERS: Final[dict[str, Callable[[_Source, Diagnostic], list[TextEdit]]]] = {
     "SARJ011": _security_fix,
     **dict.fromkeys(_COMMENT_CODES, _comment_fix),
     **dict.fromkeys(_WALRUS_CODES, _walrus_fix),
-    **dict.fromkeys({"SARJ050", "SARJ086", "SARJ087", "SARJ092", "SARJ420"}, _docstring_fix),
+    **dict.fromkeys({"SARJ050", "SARJ086", "SARJ087", "SARJ092", "SARJ099", "SARJ420"}, _docstring_fix),
     "SARJ023": _stepdown_fix,
     "SARJ024": _repeated_fix,
     "SARJ032": _exhaustiveness_fix,

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/_autofix_comments.py

@@ -9,7 +9,8 @@ from typing import TYPE_CHECKING, final
 from sarj_rule_contracts import TextEdit
 
 from sarj_python_lint.rule_base import Severity
-from sarj_python_lint.rules.excessive_commentary import empty_collection_name
+from sarj_python_lint.rules._comment_narration import CommentNarration, same_words
+from sarj_python_lint.rules._prose_budget import groups
 from sarj_python_lint.rules.trailing_value_narration import UNIT_WORDS, number_key
 
 
@@ -18,16 +19,12 @@ if TYPE_CHECKING:
     from sarj_python_lint.rule_base import Diagnostic
 
 
-_IDENTIFIER = re.compile(r"[a-z]+(?:_[a-z]+)+\Z")
-_WORDS = re.compile(r"[A-Za-z]+(?:\s+[A-Za-z]+)*\.?\Z")
 _NUMBER_AND_UNIT = re.compile(r"([0-9][0-9_]*(?:\.[0-9_]+)?)\s*([A-Za-z]+)\Z")
 _UNUSED_API_DIRECTIVE = re.compile(
     r"#\s*ruff:\s*(?:noqa\s*:\s*TID251|file-ignore\s*\[\s*(?:TID251|banned-api)\s*\])\s*\Z",
     re.IGNORECASE,
 )
 _MIN_PARAGRAPH_LINES = 4
-_INITIALIZER_AND_RETURN_COUNT = 2
-_ACCUMULATOR_METHODS = frozenset({"add", "append", "extend", "update"})
 
 
 @final
@@ -46,6 +43,8 @@ class CommentFixes:
         self.statements: dict[int, list[ast.stmt]] = {}
         for statement in context.nodes(ast.stmt):
             self.statements.setdefault(statement.lineno, []).append(statement)
+        self.prose_groups = {(group.line, group.col): group for group in groups(context.path, context.source)}
+        self.narration: CommentNarration | None = None
 
     def fixes(self, diagnostic: Diagnostic) -> list[TextEdit]:
         token = self.comments.get(diagnostic.line)
@@ -82,7 +81,7 @@ class CommentFixes:
                 return (
                     statement.col_offset == comment.start[1]
                     and statement.lineno == statement.end_lineno
-                    and _same_words(comment, name)
+                    and same_words(comment.string.removeprefix("#").strip(), name)
                 )
             case _:
                 return False
@@ -116,35 +115,19 @@ class CommentFixes:
                 return False
 
     def _restates_accumulation(self, first: tokenize.TokenInfo) -> list[tokenize.TokenInfo]:
-        paragraph: list[tokenize.TokenInfo] = []
-        line = first.start[0]
-        while (comment := self.comments.get(line)) is not None:
-            if comment.start[1] != first.start[1] or self.lines[line - 1][: comment.start[1]].strip():
-                return []
-            paragraph.append(comment)
-            line += 1
-        if len(paragraph) < _MIN_PARAGRAPH_LINES:
+        group = self.prose_groups.get((first.start[0], first.start[1] + 1))
+        if group is None:
             return []
-        initialized = self._only_statement(line)
-        if initialized is None or (name := empty_collection_name(initialized, self.context)) is None:
-            return []
-        owner = self.context.parents.get(initialized)
-        if not isinstance(owner, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            return []
-        if len(owner.body) != len(paragraph) + _INITIALIZER_AND_RETURN_COUNT or owner.body[0] is not initialized:
-            return []
-        returned = owner.body[-1]
+        if self.narration is None:
+            self.narration = CommentNarration(self.context)
+        matched = self.narration.match(group)
         if (
-            not isinstance(returned, ast.Return)
-            or not isinstance(returned.value, ast.Name)
-            or returned.value.id != name
+            matched is not None
+            and matched.kind == "accumulation"
+            and len(matched.comment_lines) >= _MIN_PARAGRAPH_LINES
         ):
-            return []
-        for comment, statement in zip(paragraph, owner.body[1:-1], strict=True):
-            called = _accumulated_call(statement, name)
-            if called is None or not _same_words(comment, called):
-                return []
-        return paragraph
+            return [self.comments[line] for line in matched.comment_lines]
+        return []
 
     def _remove(self, comment: tokenize.TokenInfo) -> TextEdit:
         line = comment.start[0]
@@ -157,16 +140,6 @@ class CommentFixes:
         )
 
 
-def _same_words(comment: tokenize.TokenInfo, identifier: str) -> bool:
-    identifier = identifier.strip("_")
-    body = comment.string.removeprefix("#").strip()
-    return (
-        _IDENTIFIER.fullmatch(identifier) is not None
-        and _WORDS.fullmatch(body) is not None
-        and body.removesuffix(".").casefold().split() == identifier.split("_")
-    )
-
-
 def _literal_name_assignment(statement: ast.stmt) -> bool:
     return (
         isinstance(statement, ast.Assign)
@@ -175,17 +148,3 @@ def _literal_name_assignment(statement: ast.stmt) -> bool:
         and isinstance(statement.value, ast.Constant)
         and isinstance(statement.value.value, (str, bytes, int, float, complex, bool, type(None)))
     )
-
-
-def _accumulated_call(statement: ast.stmt, collection: str) -> str | None:
-    match statement:
-        case ast.Expr(
-            value=ast.Call(
-                func=ast.Attribute(value=ast.Name(id=name), attr=method),
-                args=[ast.Call(func=ast.Name(id=called), args=[], keywords=[])],
-                keywords=[],
-            )
-        ):
-            return called if name == collection and method in _ACCUMULATOR_METHODS else None
-        case _:
-            return None

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/_autofix_docs.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import ast
 from functools import cached_property
-from io import StringIO
+from io import BytesIO, StringIO
 import re
+import tokenize
 from typing import TYPE_CHECKING, final
 
 from sarj_rule_contracts import TextEdit
@@ -12,8 +13,10 @@ from sarj_python_lint._autofix_inert import inert_private_scope
 from sarj_python_lint.rule_base import Severity
 from sarj_python_lint.rules import REGISTRY
 from sarj_python_lint.rules._closed_helpers import dynamic_namespace
-from sarj_python_lint.rules._docstrings import ARG_SECTIONS, section_ranges
+from sarj_python_lint.rules._comments import has_legal_notice
+from sarj_python_lint.rules._docstrings import ARG_SECTIONS, docstring_expression, section_ranges
 from sarj_python_lint.rules._prose_budget import groups
+from sarj_python_lint.rules.no_unnecessary_docstring import module_docstring_may_escape
 
 
 if TYPE_CHECKING:
@@ -178,6 +181,13 @@ class DocstringFixes:
         )
 
     def fixes(self, diagnostic: Diagnostic) -> list[TextEdit]:
+        if diagnostic.code in {"SARJ099", "SARJ420"}:
+            module_edits = self._module(diagnostic)
+            if module_edits:
+                return module_edits
+        return self._function(diagnostic)
+
+    def _function(self, diagnostic: Diagnostic) -> list[TextEdit]:
         for owner in self.context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
             if not owner.body or not private_unescaped_function(owner, self.context):
                 continue
@@ -196,33 +206,87 @@ class DocstringFixes:
             return self._labels(expression, diagnostic)
         return []
 
+    def _module(self, diagnostic: Diagnostic) -> list[TextEdit]:
+        tree = self.context.tree
+        if tree is None or not tree.body:
+            return []
+        expression = docstring_expression(tree)
+        if expression is None:
+            return []
+        if (
+            (expression.lineno, expression.col_offset + 1) not in self.unconsumed
+            or diagnostic.line != expression.lineno
+            or self._standalone(expression) is None
+        ):
+            return []
+        if (
+            dynamic_namespace(self.context)
+            or frame_metadata_observed(self.context)
+            or any(node.attr == "modules" for node in self.context.nodes(ast.Attribute))
+            or any(node.attr == "import_module" for node in self.context.nodes(ast.Attribute))
+            or any(node.name == "import_module" for node in self.context.nodes(ast.alias))
+        ):
+            return []
+        if module_docstring_may_escape(self.context):
+            return []
+        if has_legal_notice(ast.get_docstring(tree, clean=False) or ""):
+            return []
+        if not self._module_header_preserved(expression):
+            return []
+        return self._remove(tree, expression)
+
+    def _module_header_preserved(self, expression: ast.Expr) -> bool:
+        end_line = expression.end_lineno or expression.lineno
+        if any(
+            token.type == tokenize.COMMENT and expression.lineno <= token.start[0] <= end_line
+            for token in tokenize.generate_tokens(StringIO(self.context.source, newline="").readline)
+        ):
+            return False
+        original = self.context.source
+        candidate = original[: self.starts[expression.lineno - 1]] + original[self.starts[end_line] :]
+        if candidate.startswith("#!") != original.startswith("#!"):
+            return False
+        try:
+            original_encoding = tokenize.detect_encoding(BytesIO(original.encode("utf-8")).readline)[0]
+            candidate_encoding = tokenize.detect_encoding(BytesIO(candidate.encode("utf-8")).readline)[0]
+        except SyntaxError, LookupError:
+            return False
+        return original_encoding == candidate_encoding
+
     def _literal(self, expression: ast.Expr) -> tuple[int, int, str] | None:
+        bounds = self._standalone(expression)
+        if bounds is None:
+            return None
+        start, end = bounds
+        literal = self.context.source[start:end]
+        if literal[:3] not in {'"""', "'''"} or literal[-3:] != literal[:3] or "\\" in literal:
+            return None
+        return start, end, literal
+
+    def _standalone(self, expression: ast.Expr) -> tuple[int, int] | None:
         end_line = expression.end_lineno
         end_column = expression.end_col_offset
         if end_line is None or end_column is None:
             return None
         start = self._offset(expression.lineno, expression.col_offset)
         end = self._offset(end_line, end_column)
-        literal = self.context.source[start:end]
-        if literal[:3] not in {'"""', "'''"} or literal[-3:] != literal[:3] or "\\" in literal:
-            return None
         if self.context.source[self.starts[expression.lineno - 1] : start].strip():
             return None
         if self.context.source[end : self.starts[end_line]].strip():
             return None
-        return start, end, literal
+        return start, end
 
     def _offset(self, line: int, byte_column: int) -> int:
         return self.starts[line - 1] + len(self.lines[line - 1].encode("utf-8")[:byte_column].decode("utf-8"))
 
-    def _remove(self, owner: _Function, expression: ast.Expr) -> list[TextEdit]:
-        if not owner.body[1:]:
+    def _remove(self, owner: ast.Module | _Function, expression: ast.Expr) -> list[TextEdit]:
+        if not owner.body[1:] and not isinstance(owner, ast.Module):
             return []
-        next_statement = owner.body[1]
         if (
-            isinstance(next_statement, ast.Expr)
-            and isinstance(next_statement.value, ast.Constant)
-            and isinstance(next_statement.value.value, str)
+            len(owner.body) > 1
+            and isinstance(owner.body[1], ast.Expr)
+            and isinstance(owner.body[1].value, ast.Constant)
+            and isinstance(owner.body[1].value.value, str)
         ):
             return []
         end_line = expression.end_lineno or expression.lineno
@@ -239,8 +303,7 @@ class DocstringFixes:
             else frozenset({"Returns", "Return", "Yields", "Yield"})
         )
         ranges = [(start, end) for name, start, end in section_ranges(value.value) if name in wanted]
-        # The detector proves redundancy only for its preferred section heading.
-        # Other heading variants can carry independent, meaningful contracts.
+        # Other section headings may carry independent contracts; only the detector-owned heading can be removed.
         if len(ranges) != 1:
             return []
         document = value.value

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/_autofix_inert.py

@@ -74,7 +74,7 @@ _PRIMITIVE_CLASSES: Final[dict[str, type[object]]] = {
 @dataclass(slots=True)
 class _Value:
     kind: _Kind
-    literal: object = None
+    literal: bool | int | float | complex | str | bytes | None = None
     known: bool = False
     items: list[_Value] = field(default_factory=list)
     function: _Function | None = None
@@ -108,7 +108,7 @@ def _constant(value: object) -> _Value:
         bytes: _Kind.BYTES,
     }
     kind = kinds.get(type(value))
-    if kind is None:
+    if kind is None or not isinstance(value, bool | int | float | complex | str | bytes | None):
         raise _UnsafeError
     return _Value(kind, value, known=True)
 

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/interpreter_argv.py

@@ -122,7 +122,7 @@ _MAX_WRAPPERS = 8
 
 
 class UnprovableCommandError(ValueError):
-    """A wrapper executable position cannot be established safely."""
+    pass
 
 
 def unwrap_command(
@@ -210,8 +210,7 @@ def _env_wrapper_index(arguments: Sequence[str]) -> int:
             index += 1
             break
         index += _env_option_size(arguments, index)
-    # Assignments follow options, including after --; later option-looking words
-    # are executable operands, not additional env options.
+    # After env assignments begin, option-looking words are executable operands, including after --.
     while index < len(arguments) and "=" in arguments[index]:
         if arguments[index].startswith("="):
             msg = "env assignment requires a nonempty variable name"
@@ -484,8 +483,7 @@ def _shell_short_option(arguments: Sequence[str], index: int, values: frozenset[
     for flag in flags:
         if flag in values:
             operand = _following_operand(arguments, index + consumed - 1)
-            # Bash shopt (-O) has a separate, version-dependent namespace. Keep
-            # it unproven until a native option contract is available.
+            # Bash shopt (-O) uses a separate versioned namespace; no native contract is proven here.
             if flag == "O" or operand not in _SHELL_NAMED_OPTIONS:
                 return ParsedOption(InterpreterInvocation("unknown"))
             consumed += 1

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/json_boundary.py

@@ -10,8 +10,8 @@ def parse_json(text: str) -> object:
         raise ValueError(message) from error
 
 
-def _unique_pairs(pairs: list[tuple[str, object]]) -> dict[str, object]:
-    result: dict[str, object] = {}
+def _unique_pairs[T](pairs: list[tuple[str, T]]) -> dict[str, T]:
+    result: dict[str, T] = {}
     for key, value in pairs:
         if key in result:
             message = f"duplicate JSON key: {key}"

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/rule_base.py

@@ -77,11 +77,7 @@ class ColumnEncoding(StrEnum):
 
 @dataclass(frozen=True, slots=True)
 class TextEdit:
-    """An exact, half-open range of one-based lines and UTF-8 byte columns.
-
-    Columns refer to decoded source without its original leading BOM.
-    """
-
+    # Coordinates are one-based UTF-8 bytes after BOM removal; end positions are exclusive.
     start_line: int
     start_col: int
     end_line: int

sarj_python_lint-1.81.0/src/sarj_python_lint/rules/_comment_narration.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import ast
+from bisect import bisect_left
+import re
+from typing import TYPE_CHECKING, Literal, NamedTuple, final
+
+from sarj_python_lint.rules._comments import comment_line_numbers, has_narration_qualifier, is_protected
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._prose_budget import ProseGroup
+
+
+_IDENTIFIER = re.compile(r"[a-z]+(?:_[a-z]+)+\Z")
+_WORDS = re.compile(r"[A-Za-z]+(?:\s+[A-Za-z]+)*\.?\Z")
+_ACCUMULATOR_METHODS = frozenset({"add", "append", "extend", "update"})
+_MIN_LINES = 2
+_MIN_WORDS = 12
+
+
+class NarrationMatch(NamedTuple):
+    kind: Literal["accumulation", "actions"]
+    comment_lines: tuple[int, ...]
+
+
+@final
+class CommentNarration:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+        self.comment_lines = tuple(sorted(comment_line_numbers(context.source)))
+        self.statements: dict[int, list[ast.stmt]] = {}
+        for statement in context.nodes(ast.stmt):
+            self.statements.setdefault(statement.lineno, []).append(statement)
+
+    def match(self, group: ProseGroup) -> NarrationMatch | None:
+        lines = group.text.splitlines()
+        if (
+            group.kind != "comment"
+            or len(lines) < _MIN_LINES
+            or len(group.text.split()) < _MIN_WORDS
+            or any(not line.strip() for line in lines)
+            or any(has_narration_qualifier(line) or is_protected(line) for line in lines)
+        ):
+            return None
+        following = self.statements.get(group.line + len(lines), [])
+        if len(following) != 1:
+            return None
+        first = following[0]
+        owner = self.context.parents.get(first)
+        if (
+            not isinstance(owner, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef))
+            or owner.body[0] is not first
+            or first.col_offset != group.col - 1
+            or self._intervening_comment(first, owner.body[-1])
+        ):
+            return None
+        if self._accumulation(owner, lines):
+            return NarrationMatch("accumulation", tuple(range(group.line, group.line + len(lines))))
+        if (
+            len(owner.body) == len(lines)
+            and not any(isinstance(node, ast.Return) for node in owner.body[:-1])
+            and all(
+                (called := _direct_action_call(statement)) is not None and same_words(line, called)
+                for line, statement in zip(lines, owner.body, strict=True)
+            )
+        ):
+            return NarrationMatch("actions", tuple(range(group.line, group.line + len(lines))))
+        return None
+
+    def _intervening_comment(self, first: ast.stmt, last: ast.stmt) -> bool:
+        index = bisect_left(self.comment_lines, first.lineno)
+        return index < len(self.comment_lines) and self.comment_lines[index] <= (last.end_lineno or last.lineno)
+
+    def _accumulation(self, owner: ast.Module | ast.FunctionDef | ast.AsyncFunctionDef, lines: list[str]) -> bool:
+        if not isinstance(owner, (ast.FunctionDef, ast.AsyncFunctionDef)) or len(owner.body) != len(lines) + 2:
+            return False
+        name = empty_collection_name(owner.body[0], self.context)
+        returned = owner.body[-1]
+        if (
+            name is None
+            or not isinstance(returned, ast.Return)
+            or not isinstance(returned.value, ast.Name)
+            or returned.value.id != name
+        ):
+            return False
+        return all(
+            (called := _accumulated_call(statement, name)) is not None and same_words(line, called)
+            for line, statement in zip(lines, owner.body[1:-1], strict=True)
+        )
+
+
+def same_words(body: str, identifier: str) -> bool:
+    identifier = identifier.strip("_")
+    return (
+        _IDENTIFIER.fullmatch(identifier) is not None
+        and _WORDS.fullmatch(body) is not None
+        and body.removesuffix(".").casefold().split() == identifier.split("_")
+    )
+
+
+def empty_collection_name(statement: ast.stmt, context: PythonFileContext) -> 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
+    ):
+        provenance = context.static_resource_provenance
+        if provenance.builtin_namespace_untouched and provenance.binding(value.func.id, value.func) is None:
+            return target.id
+    return None
+
+
+def _direct_action_call(statement: ast.stmt) -> str | None:
+    match statement:
+        case ast.Expr(value=value) | ast.Assign(targets=[ast.Name()], value=value) | ast.Return(value=value):
+            return _zero_argument_call(value)
+        case _:
+            return None
+
+
+def _zero_argument_call(value: ast.AST | None) -> str | None:
+    match value:
+        case ast.Call(func=ast.Name(id=called), args=[], keywords=[]):
+            return called
+        case _:
+            return None
+
+
+def _accumulated_call(statement: ast.stmt, collection: str) -> str | None:
+    match statement:
+        case ast.Expr(
+            value=ast.Call(
+                func=ast.Attribute(value=ast.Name(id=name), attr=method),
+                args=[value],
+                keywords=[],
+            )
+        ):
+            return _zero_argument_call(value) if name == collection and method in _ACCUMULATOR_METHODS else None
+        case _:
+            return None

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/rules/_comments.py

@@ -16,6 +16,16 @@ if TYPE_CHECKING:
     from pathlib import Path
 
 
+_LICENSE_RE = re.compile(
+    r"copyright|license|licen[cs]ed|spdx|permission is hereby granted|all rights reserved",
+    re.IGNORECASE,
+)
+
+
+def has_legal_notice(body: str) -> bool:
+    return bool(_LICENSE_RE.search(body))
+
+
 # S1 — external references: URLs, tickets, RFCs, PEPs, CVEs, issues, and handles.
 _REF_RE = re.compile(
     r"https?://|\bRFC[- ]?\d+|\bPEP[- ]?\d+|\bCVE-\d{4}|"
@@ -57,7 +67,7 @@ _NEGATION_RE = re.compile(
 # S6 — upstream/vendor quirk, workaround provenance, or an external contract.
 _UPSTREAM_RE = re.compile(
     r"\b(?:upstream|workaround|quirk|backport|vendored|regression|fixed upstream|"
-    r"requires?\b|convention\b|rate.?limit|deprecat|opts? in(?:to)?\b|"
+    r"require[sd]?\b|convention\b|rate.?limit|deprecat|opts? in(?:to)?\b|"
     r"raises?\b.{0,60}\b(?:when|if|unless)\b)",
     re.IGNORECASE,
 )
@@ -113,6 +123,32 @@ def has_external_reference(body: str) -> bool:
     return bool(_REF_RE.search(body))
 
 
+_NARRATION_MODALITY_RE = re.compile(r"\b(?:can|could|should|shall|may|might|must|will|would|cannot)\b", re.IGNORECASE)
+_NARRATION_LEAD_IN_RE = re.compile(r":$")
+_NARRATION_EMPHASIS_RE = re.compile(r"\*\w[^*]*\*|`[^`]+`")
+_NARRATION_NEGATION_RE = re.compile(r"\b(?:no|not|never|neither|nor|without|none|non)\b", re.IGNORECASE)
+_NARRATION_QUALIFIER_RE = re.compile(
+    r"\b(?:all|any|both|each|every|some|only|need|needs|needed|require|requires|required)\b|"
+    r"^\s*(?:and|after|before|finally|given|next|then|when)\b",
+    re.IGNORECASE,
+)
+_NARRATION_NAVIGATION_RE = re.compile(r"^\s*(?:sheet|slide|step)\s+\d+\s*(?:[:.\-]|$)", re.IGNORECASE)
+
+
+def has_narration_qualifier(body: str) -> bool:
+    return any(
+        pattern.search(body)
+        for pattern in (
+            _NARRATION_MODALITY_RE,
+            _NARRATION_LEAD_IN_RE,
+            _NARRATION_EMPHASIS_RE,
+            _NARRATION_NEGATION_RE,
+            _NARRATION_QUALIFIER_RE,
+            _NARRATION_NAVIGATION_RE,
+        )
+    )
+
+
 # Below this length an inflection strip would eat the word itself.
 _MIN_STEM_LENGTH = 3
 

{sarj_python_lint-1.77.3 → sarj_python_lint-1.81.0}/src/sarj_python_lint/rules/_data_union_discriminator.py

@@ -124,7 +124,7 @@ class _DataUnions:
                     message=f"Data union `{name}` has no shared disjoint Literal discriminator. "
                     "Add a common field such as `kind` or `scope` with non-overlapping Literal values "
                     "on every variant; preserve constructor and serialized contracts when choosing defaults.",
-                    severity=Severity.WARNING,
+                    severity=Severity.ERROR,
                 )
             )
         return findings