sarj-python-lint 1.27.4__tar.gz → 1.28.0__tar.gz

{sarj_python_lint-1.27.4 → sarj_python_lint-1.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.27.4
+Version: 1.28.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.27.4 → sarj_python_lint-1.28.0}/pyproject.toml

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

{sarj_python_lint-1.27.4 → sarj_python_lint-1.28.0}/src/sarj_python_lint/interpreter_argv.py

@@ -29,6 +29,7 @@ class ParsedOption:
     invocation: InterpreterInvocation | None = None
     consumed: int = 1
     stdin_mode: bool = False
+    command_mode: bool = False
 
 
 _SHELLS = frozenset({"sh", "bash", "dash", "zsh", "ksh"})
@@ -112,6 +113,7 @@ _WRAPPER_VALUES = MappingProxyType(
             }
         ),
         "timeout": frozenset({"-s", "--signal", "-k", "--kill-after"}),
+        "dumb-init": frozenset(),
     }
 )
 _MAX_WRAPPERS = 8
@@ -136,6 +138,8 @@ def unwrap_command(
             continue
         if command not in _WRAPPER_VALUES or (allowed_wrappers is not None and command not in allowed_wrappers):
             return current
+        # dumb-init uses execvp; its child cannot be a shell builtin.
+        allow_shell_builtins = allow_shell_builtins and command != "dumb-init"
         current = current[_value_wrapper_index(current, command) :]
     msg = "command wrapper nesting exceeds analysis bound"
     raise UnprovableCommandError(msg)
@@ -160,6 +164,8 @@ def _command_wrapper_index(arguments: Sequence[str], command: str) -> int:
 def _value_wrapper_index(arguments: Sequence[str], command: str) -> int:
     if command == "env":
         return _env_wrapper_index(arguments)
+    if command == "dumb-init":
+        return _dumb_init_wrapper_index(arguments)
     index = 1
     while index < len(arguments):
         argument = arguments[index]
@@ -173,6 +179,24 @@ def _value_wrapper_index(arguments: Sequence[str], command: str) -> int:
     return index + int(command == "timeout")
 
 
+def _dumb_init_wrapper_index(arguments: Sequence[str]) -> int:
+    index = 1
+    while index < len(arguments):
+        argument = arguments[index]
+        if argument in {"-h", "--help", "-V", "--version"}:
+            return len(arguments)
+        if argument == "--":
+            index += 1
+            break
+        if not argument.startswith("-") or argument == "-":
+            break
+        if argument not in {"-c", "--single-child", "-v", "--verbose"}:
+            msg = "unsupported dumb-init wrapper option"
+            raise UnprovableCommandError(msg)
+        index += 1
+    return index
+
+
 def _env_wrapper_index(arguments: Sequence[str]) -> int:
     index = 1
     while index < len(arguments) and arguments[index].startswith("-"):
@@ -237,7 +261,7 @@ def classify_interpreter(argv: Sequence[str]) -> InterpreterInvocation:
         return _python(arguments[1:])
     if executable in _SHELLS:
         return _short_options(
-            arguments[1:], source="c", values=frozenset({"o", "O"}), shell_mode=True, bash_mode=executable == "bash"
+            arguments[1:], source="c", values=frozenset({"o", "O"}), shell_mode=True, shell_name=executable
         )
     if executable in {"node", "nodejs"}:
         return _node(arguments[1:])
@@ -342,13 +366,21 @@ def _ruby_long_option(argument: str, following: str | None) -> ParsedOption:
 
 
 def _short_options(
-    arguments: Sequence[str], *, source: str, values: frozenset[str], shell_mode: bool = False, bash_mode: bool = False
+    arguments: Sequence[str], *, source: str, values: frozenset[str], shell_mode: bool = False, shell_name: str = ""
 ) -> InterpreterInvocation:
     index = 0
     stdin_mode = False
+    command_mode = False
     short_seen = False
+    bash_mode = shell_name == "bash"
+    validated_shell = shell_name in {"bash", "sh", "dash"}
     while index < len(arguments):
         boundary = _external_boundary(arguments, index, plus_options=True)
+        if boundary is not None and command_mode:
+            index += int(arguments[index] in {"-", "--"})
+            if index >= len(arguments):
+                return InterpreterInvocation("unknown")
+            return InterpreterInvocation("shell", arguments[index], tuple(arguments[index + 2 :]))
         if boundary is not None:
             return InterpreterInvocation("stdin") if stdin_mode else boundary
         argument = arguments[index]
@@ -357,13 +389,14 @@ def _short_options(
         else:
             short_seen = True
             parsed = _short_option(
-                arguments, index, source=source, values=values, shell_mode=shell_mode, bash_mode=bash_mode
+                arguments, index, source=source, values=values, shell_mode=shell_mode, validated_shell=validated_shell
             )
         if parsed.invocation is not None:
             return parsed.invocation
         stdin_mode = stdin_mode or parsed.stdin_mode
+        command_mode = command_mode or parsed.command_mode
         index += parsed.consumed
-    return InterpreterInvocation("stdin")
+    return InterpreterInvocation("unknown" if command_mode else "stdin")
 
 
 def _long_option(
@@ -395,18 +428,23 @@ def _short_option(
     source: str,
     values: frozenset[str],
     shell_mode: bool,
-    bash_mode: bool = False,
+    validated_shell: bool = False,
 ) -> ParsedOption:
-    if bash_mode:
+    if validated_shell:
         return _shell_short_option(arguments, index, values)
     argument = arguments[index]
     for cursor, flag in enumerate(argument[1:], 1):
         if flag in source:
-            attached = "" if shell_mode else argument[cursor + 1 :]
+            if shell_mode:
+                if not values.isdisjoint(argument[cursor + 1 :]):
+                    return ParsedOption(InterpreterInvocation("unknown"))
+                return ParsedOption(command_mode=True)
+            attached = argument[cursor + 1 :]
             operand = attached or _following_operand(arguments, index)
-            forwarded = tuple(arguments[index + 3 :]) if shell_mode else ()
-            return ParsedOption(InterpreterInvocation("shell" if shell_mode else "inline", operand, forwarded))
+            return ParsedOption(InterpreterInvocation("inline", operand))
         if flag in values:
+            if shell_mode and (flag == "O" or argument[cursor + 1 :] == "c"):
+                return ParsedOption(InterpreterInvocation("unknown"))
             return ParsedOption(consumed=1 + int(cursor + 1 == len(argument)))
     return ParsedOption()
 
@@ -424,11 +462,7 @@ def _shell_short_option(arguments: Sequence[str], index: int, values: frozenset[
             if flag == "O" or operand not in _SHELL_NAMED_OPTIONS:
                 return ParsedOption(InterpreterInvocation("unknown"))
             consumed += 1
-    if "c" in flags:
-        operand = _following_operand(arguments, index + consumed - 1)
-        forwarded = tuple(arguments[index + consumed + 2 :])
-        return ParsedOption(InterpreterInvocation("shell", operand, forwarded))
-    return ParsedOption(consumed=consumed, stdin_mode="s" in flags)
+    return ParsedOption(consumed=consumed, stdin_mode="s" in flags, command_mode="c" in flags)
 
 
 def _node(arguments: Sequence[str]) -> InterpreterInvocation:

sarj_python_lint-1.28.0/src/sarj_python_lint/rules/_closed_helpers.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+_DYNAMIC_NAMES = frozenset(
+    {"globals", "locals", "vars", "eval", "exec", "getattr", "setattr", "delattr", "__import__", "__all__"}
+)
+
+
+def dynamic_namespace(context: PythonFileContext) -> bool:
+    return (
+        any(node.id in _DYNAMIC_NAMES for node in context.nodes(ast.Name))
+        or any(node.attr in _DYNAMIC_NAMES | {"__dict__"} for node in context.nodes(ast.Attribute))
+        or any(node.name == "*" for node in context.nodes(ast.alias))
+    )
+
+
+def executable_body(function: ast.FunctionDef) -> list[ast.stmt]:
+    body = function.body
+    return (
+        body[1:]
+        if body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+        else body
+    )
+
+
+def closed_references(
+    context: PythonFileContext, function: ast.FunctionDef, provenance: ResourceProvenance
+) -> list[ast.Name] | None:
+    if (
+        context.parents.get(function) is not context.tree
+        or not function.name.startswith("_")
+        or function.name.startswith("__")
+        or function.decorator_list
+        or function.type_params
+    ):
+        return None
+    if (
+        function.args.vararg is not None
+        or function.args.kwarg is not None
+        or dynamic_namespace(context)
+        or any(node.attr == function.name for node in context.nodes(ast.Attribute))
+        or any(
+            isinstance(node.value, str) and function.name in node.value.split(".")
+            for node in context.nodes(ast.Constant)
+        )
+    ):
+        return None
+    references = [node for node in context.nodes(ast.Name) if node.id == function.name]
+    if not references or any(
+        not isinstance(node.ctx, ast.Load) or provenance.binding(node.id, node) is not function for node in references
+    ):
+        return None
+    return references
+
+
+def direct_call(reference: ast.Name, context: PythonFileContext) -> ast.Call | None:
+    parent = context.parents.get(reference)
+    if not isinstance(parent, ast.Call) or parent.func is not reference:
+        return None
+    if any(isinstance(argument, ast.Starred) for argument in parent.args) or any(
+        keyword.arg is None for keyword in parent.keywords
+    ):
+        return None
+    return parent
+
+
+def call_matches(function: ast.FunctionDef, call: ast.Call) -> bool:
+    positional = [*function.args.posonlyargs, *function.args.args]
+    keywords = {arg.arg for arg in (*function.args.args, *function.args.kwonlyargs)}
+    required = {arg.arg for arg in positional[: len(positional) - len(function.args.defaults)]}
+    required.update(
+        arg.arg
+        for arg, default in zip(function.args.kwonlyargs, function.args.kw_defaults, strict=True)
+        if default is None
+    )
+    supplied = {arg.arg for arg in positional[: len(call.args)]}
+    if len(call.args) > len(positional):
+        return False
+    for keyword in call.keywords:
+        if keyword.arg not in keywords or keyword.arg in supplied:
+            return False
+        supplied.add(keyword.arg)
+    return required <= supplied
+
+
+def stable_class(context: PythonFileContext, declaration: ast.ClassDef, provenance: ResourceProvenance) -> bool:
+    if declaration.decorator_list or declaration.keywords or context.parents.get(declaration) is not context.tree:
+        return False
+    return provenance.bindings.get(context.tree, {}).get(declaration.name) == [declaration]

{sarj_python_lint-1.27.4 → sarj_python_lint-1.28.0}/src/sarj_python_lint/rules/_registry.py

@@ -207,6 +207,11 @@ if TYPE_CHECKING:
     from collections.abc import Mapping
 
     from sarj_python_lint.rule_base import Rule
+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.redundant_test_constructor_forwarder import RedundantTestConstructorForwarder
+from sarj_python_lint.rules.repeated_unimplemented_test_contract import RepeatedUnimplementedTestContract
+
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
@@ -348,5 +353,9 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferRegexFullmatch.id: PreferRegexFullmatch,
         PreferMonotonicForElapsedTime.id: PreferMonotonicForElapsedTime,
         TypedErrorReasons.id: TypedErrorReasons,
+        RedundantTestConstructorForwarder.id: RedundantTestConstructorForwarder,
+        DuplicateAdjacentExceptionHandler.id: DuplicateAdjacentExceptionHandler,
+        DuplicateClosedPureHelper.id: DuplicateClosedPureHelper,
+        RepeatedUnimplementedTestContract.id: RepeatedUnimplementedTestContract,
     }
 )

sarj_python_lint-1.28.0/src/sarj_python_lint/rules/duplicate_adjacent_exception_handler.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import ast
+import builtins
+from pathlib import PurePosixPath
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    cast,  # ruff: ignore[banned-api] -- vars exposes Any; the object view permits isinstance narrowing.
+    final,
+    override,
+)
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    ProjectRule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._closed_helpers import dynamic_namespace, stable_class
+from sarj_python_lint.rules._paths import is_generated
+from sarj_python_lint.rules._project_index import ProjectIndexSet
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+from sarj_python_lint.rules._suppression_comments import scan_comments
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._project_index import SourceUnit, SymbolRef
+    from sarj_python_lint.rules._suppression_comments import Comment
+
+
+_BUILTIN_NAMESPACE = cast("Mapping[str, object]", vars(builtins))
+_BUILTIN_EXCEPTIONS = frozenset(
+    name for name, value in _BUILTIN_NAMESPACE.items() if isinstance(value, type) and issubclass(value, Exception)
+)
+_BAD = "try:\n    action()\nexcept ValueError as error:\n    raise RuntimeError('invalid') from error\nexcept TypeError as error:\n    raise RuntimeError('invalid') from error\n"
+_GOOD = "try:\n    action()\nexcept (ValueError, TypeError) as error:\n    raise RuntimeError('invalid') from error\n"
+
+
+@final
+class DuplicateAdjacentExceptionHandler(ProjectRule):
+    id = "duplicate-adjacent-exception-handler"
+    code = "SARJ488"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Adjacent exception handlers repeat the same executable translation.",
+        rationale="Repeating one translation for adjacent statically known exception classes creates extra branches to maintain without different behavior.",
+        remediation="Consider one tuple handler for the adjacent exception types. Preserve distinct messages, cleanup, ordering, and intentional independently maintained translations.",
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only ordinary try statements with adjacent handlers, identical exception bindings, executable ASTs and comments are compared; exception groups and bare re-raise/pass handlers are excluded.",
+            "Handler types must be simple names or tuples of unshadowed builtin or statically resolved first-party Exception subclasses, with unconditional stable declarations/imports.",
+            "Dynamic namespace access, unknown external exception classes, generated/vendor sources, different comments, and intervening handlers are excluded. No autofix preserves intentional translation seams.",
+        ),
+        examples=tuple(
+            RuleExample(
+                example_id=name,
+                title=title,
+                outcome=outcome,
+                files=(ExampleFile.python("app/service.py", source),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=count,
+                public=True,
+            )
+            for name, title, outcome, source, count in (
+                ("repeated-translation", "Adjacent handlers translate identically", ExampleOutcome.MATCH, _BAD, 1),
+                ("one-tuple-handler", "One handler owns the shared translation", ExampleOutcome.NO_MATCH, _GOOD, 0),
+            )
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        tree = context.tree
+        if context.generated or tree is None or "except" not in context.symbol_source or dynamic_namespace(context):
+            return []
+        project = context.session.project or ProjectIndexSet.single(context.path, context.source)
+        unit = project.unit_or_source(context.path, context.source, tree)
+        provenance = ResourceProvenance(context)
+        comments = scan_comments(context.source)
+        findings: list[Diagnostic] = []
+        for statement in context.nodes(ast.Try):
+            previous: ast.ExceptHandler | None = None
+            reported = False
+            for handler in statement.handlers:
+                safe = _safe_types(handler.type, context, provenance, project, unit, seen=set())
+                if previous is not None and safe and _same_translation(previous, handler, comments):
+                    if not reported and not is_suppressed(context.source_lines, handler.lineno, self.code):
+                        findings.append(
+                            Diagnostic(
+                                path=context.path,
+                                line=handler.lineno,
+                                col=handler.col_offset + 1,
+                                code=self.code,
+                                severity=Severity.WARNING,
+                                message="Adjacent exception handlers have identical translations; consider one tuple handler, preserving intentional separate error contracts.",
+                            )
+                        )
+                    reported = True
+                else:
+                    reported = False
+                previous = handler if safe else None
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+def _same_translation(first: ast.ExceptHandler, second: ast.ExceptHandler, comments: list[Comment]) -> bool:
+    if first.name != second.name or not first.body or first.type is None or second.type is None:
+        return False
+    if not {node.id for node in ast.walk(first.type) if isinstance(node, ast.Name)}.isdisjoint(
+        node.id for node in ast.walk(second.type) if isinstance(node, ast.Name)
+    ):
+        return False
+    if len(first.body) == 1 and (
+        isinstance(first.body[0], ast.Pass) or (isinstance(first.body[0], ast.Raise) and first.body[0].exc is None)
+    ):
+        return False
+    if ast.dump(ast.Module(body=first.body, type_ignores=[])) != ast.dump(
+        ast.Module(body=second.body, type_ignores=[])
+    ):
+        return False
+    if any((first.end_lineno or first.lineno) < comment.line < second.lineno for comment in comments):
+        return False
+    return _comments(first, comments) == _comments(second, comments)
+
+
+def _comments(handler: ast.ExceptHandler, comments: list[Comment]) -> list[str]:
+    return [
+        comment.body for comment in comments if handler.lineno <= comment.line <= (handler.end_lineno or handler.lineno)
+    ]
+
+
+def _safe_types(
+    expression: ast.expr | None,
+    context: PythonFileContext,
+    provenance: ResourceProvenance,
+    project: ProjectIndexSet,
+    unit: SourceUnit | None,
+    *,
+    seen: set[SymbolRef],
+) -> bool:
+    if isinstance(expression, ast.Tuple):
+        return bool(expression.elts) and all(
+            _safe_types(element, context, provenance, project, unit, seen=seen) for element in expression.elts
+        )
+    if not isinstance(expression, ast.Name):
+        return False
+    if (
+        expression.id in _BUILTIN_EXCEPTIONS
+        and context.imports.builtin_is_unshadowed(expression.id)
+        and provenance.binding(expression.id, expression) is None
+    ):
+        return True
+    return _first_party_exception(expression, context, provenance, project, unit, seen=seen)
+
+
+def _first_party_exception(
+    expression: ast.Name,
+    context: PythonFileContext,
+    provenance: ResourceProvenance,
+    project: ProjectIndexSet,
+    unit: SourceUnit | None,
+    *,
+    seen: set[SymbolRef],
+) -> bool:
+    from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- defer until the rule registry finishes loading.
+
+    binding = provenance.binding(expression.id, expression)
+    if not isinstance(binding, ast.ClassDef | ast.alias) or unit is None:
+        return False
+    if isinstance(binding, ast.alias):
+        statement = context.parents.get(binding)
+        if statement is None or context.parents.get(statement) is not context.tree:
+            return False
+    summary = project.class_for(unit, expression)
+    if (
+        summary is None
+        or summary.symbol in seen
+        or (owner := project.source_unit(summary.symbol.module)) is None
+        or owner.tree is None
+        or is_generated(owner.path, owner.source)
+    ):
+        return False
+    definition_context = (
+        context if owner.path == context.path else PythonFileContext(owner.path, owner.source, context.session)
+    )
+    definition_provenance = provenance if definition_context is context else ResourceProvenance(definition_context)
+    declaration = next(
+        (node for node in definition_context.nodes(ast.ClassDef) if node.name == summary.symbol.name), None
+    )
+    return (
+        declaration is not None
+        and stable_class(definition_context, declaration, definition_provenance)
+        and len(declaration.bases) == 1
+        and _safe_types(
+            declaration.bases[0],
+            definition_context,
+            definition_provenance,
+            project,
+            owner,
+            seen=seen | {summary.symbol},
+        )
+    )