sarj-python-lint 1.16.2__tar.gz → 1.16.4__tar.gz

{sarj_python_lint-1.16.2 → sarj_python_lint-1.16.4}/PKG-INFO

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

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

{sarj_python_lint-1.16.2 → sarj_python_lint-1.16.4}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -101,7 +101,8 @@ class PreferMatchTypeDispatch(Rule):
         limitations=(
             "General dispatch requires three or more adjacent, unguarded `isinstance` branches over the same simple name. Two arms are checked only for an exact `ast.Name.id` / `ast.Attribute.attr` projection followed by a None-returning fallback.",
             "A terminating sibling prefix may precede a two-arm if/elif tail whose bodies can fall through. Preserve nested checks inside case bodies rather than moving them into case guards.",
-            "The checked types must be unshadowed builtins, undecorated module-local classes without an explicit metaclass, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "The checked types must be unshadowed builtins, undecorated module-local classes without an explicit or known locally inherited custom metaclass, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "Local ancestry must resolve to stable undeclared-metaclass classes or proven builtin/stdlib ast bases. External bases, runtime base aliases, and parameterized base expressions remain excluded because their metaclass or __class_getitem__ effects are unproven.",
             "Nested attribute-validation guards are excluded: converting them to keyword class patterns can turn attribute errors into match fallthrough, and an imported isinstance operand may be a runtime tuple rather than a class.",
             "A terminal-looking context-manager body does not prove a sibling branch terminates: exceptions can be suppressed. An unconditional return or raise after the context manager remains eligible.",
             "Declared support for Python before 3.10 suppresses this recommendation when proven by the nearest project metadata or exact installed-distribution ownership. Missing or ambiguous target metadata retains advisory behavior; it does not prove a modern target.",
@@ -239,20 +240,20 @@ class PreferMatchTypeDispatch(Rule):
             return []
         imports = context.imports
         all_nodes = tuple(context.nodes(ast.AST))
-        unsafe_bindings = _unsafe_local_bound_names(tree, all_nodes) | frozenset(
+        unsafe_bindings = _unsafe_local_bound_names(tree, all_nodes, imports) | frozenset(
             qualified
             for node in all_nodes
             if isinstance(node, ast.Attribute)
             and isinstance(node.ctx, (ast.Store, ast.Del))
             and (qualified := imports.resolved_qualified_name(node)) is not None
-            and qualified.startswith("ast.")
+            and qualified.startswith(("ast.", "builtins."))
         )
         has_wildcard_import = any(
             isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names) for node in all_nodes
         )
         if not imports.builtin_is_unshadowed("isinstance") or "isinstance" in unsafe_bindings or has_wildcard_import:
             return []
-        local_classes = _unshadowed_module_classes(tree, all_nodes)
+        local_classes = _unshadowed_module_classes(tree, all_nodes, imports, unsafe_bindings)
         findings = _ladder_findings(
             all_nodes,
             path,
@@ -287,14 +288,10 @@ class PreferMatchTypeDispatch(Rule):
         return findings
 
 
-def _unshadowed_module_classes(tree: ast.Module, all_nodes: tuple[ast.AST, ...]) -> frozenset[str]:
-    classes = [
-        statement.name
-        for statement in tree.body
-        if isinstance(statement, ast.ClassDef)
-        and not statement.decorator_list
-        and not any(keyword.arg in {"metaclass", None} for keyword in statement.keywords)
-    ]
+def _unshadowed_module_classes(
+    tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> frozenset[str]:
+    declarations = [statement for statement in tree.body if isinstance(statement, ast.ClassDef)]
     rebound: set[str] = set()
     for node in all_nodes:
         match node:
@@ -310,17 +307,83 @@ def _unshadowed_module_classes(tree: ast.Module, all_nodes: tuple[ast.AST, ...])
             case _:
                 pass
     _add_module_import_bindings(tree, rebound)
-    return frozenset(name for name in classes if classes.count(name) == 1 and name not in rebound)
+    names = [declaration.name for declaration in declarations]
+    stable = [
+        declaration
+        for declaration in declarations
+        if names.count(declaration.name) == 1 and declaration.name not in rebound
+    ]
+    nominal = _nominal_class_ancestry(stable, imports, unsafe_bindings)
+    return frozenset(
+        declaration.name
+        for declaration in stable
+        if declaration.name in nominal
+        and not any(keyword.arg in {"metaclass", None} for keyword in declaration.keywords)
+    )
 
 
-def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...]) -> frozenset[str]:
-    module_imports = {id(statement) for statement in tree.body if isinstance(statement, (ast.Import, ast.ImportFrom))}
-    names = {
-        alias.asname or alias.name.partition(".")[0]
-        for statement in all_nodes
-        if isinstance(statement, (ast.Import, ast.ImportFrom)) and id(statement) not in module_imports
-        for alias in statement.names
-    }
+def _nominal_class_ancestry(
+    declarations: list[ast.ClassDef], imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> frozenset[str]:
+    proven: frozenset[str] = frozenset()
+    while True:
+        nominal = frozenset(
+            declaration.name
+            for declaration in declarations
+            if not declaration.decorator_list
+            and not _unproven_metaclass_header(declaration, imports, unsafe_bindings)
+            and all(_nominal_base(base, imports, proven, unsafe_bindings) for base in declaration.bases)
+        )
+        if nominal <= proven:
+            return proven
+        proven |= nominal
+
+
+def _nominal_base(
+    expression: ast.expr, imports: ImportIndex, local_classes: frozenset[str], unsafe_bindings: frozenset[str]
+) -> bool:
+    if isinstance(expression, ast.Subscript):
+        return False
+    return _type_reference(expression, imports, local_classes, unsafe_bindings) is not None or (
+        _builtin_class_reference(expression, imports, unsafe_bindings) is not None
+    )
+
+
+def _unproven_metaclass_header(
+    declaration: ast.ClassDef, imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> bool:
+    for keyword in declaration.keywords:
+        if keyword.arg is None:
+            return True
+        if keyword.arg != "metaclass":
+            continue
+        if _builtin_class_reference(keyword.value, imports, unsafe_bindings) == "type":
+            continue
+        return True
+    return False
+
+
+def _builtin_class_reference(expression: ast.expr, imports: ImportIndex, unsafe_bindings: frozenset[str]) -> str | None:
+    root = expression
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    if not isinstance(root, ast.Name) or root.id in unsafe_bindings:
+        return None
+    if (
+        isinstance(expression, ast.Name)
+        and expression.id in _BUILTIN_TYPES
+        and imports.builtin_is_unshadowed(expression.id)
+        and f"builtins.{expression.id}" not in unsafe_bindings
+    ):
+        return expression.id
+    symbol = imports.resolved_symbol(expression, sources=frozenset({"builtins"}))
+    if symbol in _BUILTIN_TYPES and f"builtins.{symbol}" not in unsafe_bindings:
+        return symbol
+    return None
+
+
+def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex) -> frozenset[str]:
+    names = _unsafe_import_bound_names(tree, all_nodes, imports)
     names.update(
         candidate.name
         for candidate in all_nodes
@@ -334,6 +397,31 @@ def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...])
     return frozenset(names)
 
 
+def _unsafe_import_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex) -> set[str]:
+    module_imports = {id(statement) for statement in tree.body if isinstance(statement, (ast.Import, ast.ImportFrom))}
+    names: set[str] = set()
+    for statement in all_nodes:
+        if not isinstance(statement, (ast.Import, ast.ImportFrom)):
+            continue
+        relative = isinstance(statement, ast.ImportFrom) and statement.level > 0
+        if id(statement) in module_imports and not relative:
+            continue
+        for alias in statement.names:
+            if not _preserves_indexed_import(statement, alias, imports):
+                names.add(alias.asname or alias.name.partition(".")[0])
+    return names
+
+
+def _preserves_indexed_import(statement: ast.Import | ast.ImportFrom, alias: ast.alias, imports: ImportIndex) -> bool:
+    local = alias.asname or alias.name.partition(".")[0]
+    target = imports.bindings.get(local)
+    if target is None:
+        return False
+    if isinstance(statement, ast.ImportFrom):
+        return not statement.level and target.module == statement.module and target.symbol == alias.name
+    return target.module == alias.name and target.symbol is None
+
+
 def _ladder_findings(
     all_nodes: tuple[ast.AST, ...],
     path: Path,
@@ -632,6 +720,7 @@ def _type_reference(
             expression.id in _BUILTIN_TYPES
             and imports.builtin_is_unshadowed(expression.id)
             and expression.id not in unsafe_bindings
+            and f"builtins.{expression.id}" not in unsafe_bindings
         ):
             return expression.id
         if expression.id in local_classes and expression.id not in unsafe_bindings:

{sarj_python_lint-1.16.2 → sarj_python_lint-1.16.4}/src/sarj_python_lint/rules/require_public_dependency_contract.py

@@ -116,7 +116,7 @@ class RequirePublicDependencyContract(ProjectRule):
         if implementation is None:
             return None
         contract = _existing_substitutable_contract(implementation, project)
-        members = _dependency_members(node, fields)
+        members = _dependency_members(node, fields, context)
         if contract is None or members is None or not members <= _public_operations(contract):
             return None
         return Diagnostic(
@@ -230,11 +230,15 @@ def _declaration(unit: SourceUnit, name: str) -> ast.ClassDef | None:
     return next((node for node in unit.tree.body if isinstance(node, ast.ClassDef) and node.name == name), None)
 
 
-def _dependency_members(node: ast.ClassDef, fields: frozenset[str]) -> frozenset[str] | None:
+def _dependency_members(
+    node: ast.ClassDef, fields: frozenset[str], context: PythonFileContext
+) -> frozenset[str] | None:
     members: set[str] = set()
     called = False
     for method in class_methods(node):
         for child in ast.walk(method):
+            if _dependency_field_escapes(child, fields, context):
+                return None
             target = child.func if isinstance(child, ast.Call) else child
             if (
                 isinstance(target, ast.Attribute)
@@ -246,3 +250,16 @@ def _dependency_members(node: ast.ClassDef, fields: frozenset[str]) -> frozenset
                 members.add(target.attr)
                 called |= isinstance(child, ast.Call) and not method.name.startswith("_")
     return frozenset(members) if called else None
+
+
+def _dependency_field_escapes(node: ast.AST, fields: frozenset[str], context: PythonFileContext) -> bool:
+    if not (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.ctx, ast.Load)
+        and isinstance(node.value, ast.Name)
+        and node.value.id == "self"
+        and node.attr in fields
+    ):
+        return False
+    parent = context.parents.get(node)
+    return not (isinstance(parent, ast.Attribute) and parent.value is node)

{sarj_python_lint-1.16.2 → sarj_python_lint-1.16.4}/src/sarj_python_lint/rules/unused_test_factory_option.py

@@ -38,15 +38,17 @@ class UnusedTestFactoryOption(Rule):
     code = "SARJ443"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="A closed test-local factory exposes a literal option that its callers never vary.",
+        summary="A private test factory exposes an invariant literal or unexercised local callable option.",
         rationale="Unused customization obscures the values that actually distinguish test scenarios.",
-        remediation="Consider keeping the invariant value in the test-local construction instead of exposing an unexercised option. Preserve shared factories and dependency-injection contracts.",
+        remediation="Consider keeping the invariant literal or stable local callable in the construction instead of exposing an unexercised option. Preserve intentional dependency contracts and callable default binding timing.",
         category=RuleCategory.TESTING,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only private _make_ and _build_ helpers nested directly inside test functions are considered, with at least two known direct callers and straight-line construction bodies.",
-            "Only literal options are considered. Callable dependency defaults, module-level/shared factories, decorated factories, escaping references, reflection, unpacking, rebinding and shadowing are excluded.",
+            "Literal findings consider only private _make_ and _build_ helpers nested directly inside test functions, with at least two known direct callers and straight-line construction bodies.",
+            "Callable findings consider module-level private helpers with the same construction shape and an earlier undecorated local function default, only when at least two known direct callers all omit that option.",
+            "Conftest callable factories, explicit callable arguments, exports, decorators, escaping references, reflection, unpacking, rebinding, shadowing and ambiguous mutation or patch targets are excluded.",
             "Same-name declarations elsewhere in the file conservatively exclude a helper. No autofix: this warning identifies unexercised customization, not an invalid callable contract.",
+            "Callable findings describe known callers in this file; cross-module and dynamic callers are not inferred. Retain intentional extension points with a reasoned exception, preserving definition-time default capture.",
         ),
         examples=(
             RuleExample(
@@ -63,6 +65,40 @@ class UnusedTestFactoryOption(Rule):
                 expected_count=1,
                 public=True,
             ),
+            RuleExample(
+                example_id="unused-local-callable-option",
+                scenario="callable-default",
+                title="Known callers do not replace a stable local dependency",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _read():\n    return 'ready'\n"
+                        "def _make_widget(*, read=_read):\n    return Widget(read=read)\n"
+                        "_make_widget()\n_make_widget()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="exercised-local-callable-option",
+                scenario="callable-default",
+                title="An explicit callback preserves the dependency contract",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _read():\n    return 'ready'\n"
+                        "def _make_widget(*, read=_read):\n    return Widget(read=read)\n"
+                        "_make_widget()\n_make_widget(read=_read)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="exercised-size-option",
                 title="Keep customization that a caller exercises",
@@ -96,14 +132,15 @@ class UnusedTestFactoryOption(Rule):
         lines = context.source_lines
         findings: list[Diagnostic] = []
         for function in context.nodes(ast.FunctionDef):
-            owner = context.parents.get(function)
-            if (
-                not _is_factory(function)
-                or not isinstance(owner, ast.FunctionDef | ast.AsyncFunctionDef)
-                or not owner.name.startswith("test_")
-            ):
+            if not _is_factory(function):
                 continue
-            findings.extend(_factory_findings(tree, function, path, lines, self.code, node_index=context.node_index))
+            owner = context.parents.get(function)
+            if isinstance(owner, ast.FunctionDef | ast.AsyncFunctionDef) and owner.name.startswith("test_"):
+                findings.extend(
+                    _factory_findings(tree, function, path, lines, self.code, node_index=context.node_index)
+                )
+            elif owner is tree and path.name != "conftest.py":
+                findings.extend(_callable_factory_findings(context, function, self.code))
         return sorted(findings, key=lambda item: (item.line, item.col))
 
 
@@ -280,3 +317,79 @@ def _factory_options(function: ast.FunctionDef) -> list[tuple[ast.arg, ast.expr]
     ]
     used = {node.id for node in nodes(function, ast.Name) if isinstance(node.ctx, ast.Load)}
     return [(argument, default) for argument, default in defaults if argument.arg in used and default is not None]
+
+
+def _callable_factory_findings(context: PythonFileContext, function: ast.FunctionDef, code: str) -> list[Diagnostic]:
+    tree = context.tree
+    if tree is None:
+        return []
+    options = [(argument, default) for argument, default in _factory_options(function) if isinstance(default, ast.Name)]
+    if not options:
+        return []
+    calls = _direct_calls(tree, function, node_index=context.node_index)
+    if len(calls) < _MIN_INVARIANT_CALLS:
+        return []
+    bound = _bound_calls(function, calls)
+    if bound is None:
+        return []
+    supplied = {name for arguments in bound for name in arguments}
+    rebound = {node.id for node in nodes(function, ast.Name) if not isinstance(node.ctx, ast.Load)}
+    findings: list[Diagnostic] = []
+    for argument, default in options:
+        if (
+            argument.arg in supplied | rebound
+            or not _is_stable_local_callable(context, function, default.id)
+            or is_suppressed(context.source_lines, argument.lineno, code)
+        ):
+            continue
+        findings.append(
+            Diagnostic(
+                path=context.path,
+                line=argument.lineno,
+                col=argument.col_offset + 1,
+                code=code,
+                severity=Severity.WARNING,
+                message=(
+                    f"No known direct caller in this file supplies `{function.name}.{argument.arg}`; consider "
+                    f"using the stable local callable `{default.id}` internally. Preserve default binding timing "
+                    "and retain the option if external callers or an intentional test contract need it."
+                ),
+            )
+        )
+    return findings
+
+
+def _is_stable_local_callable(context: PythonFileContext, factory: ast.FunctionDef, name: str) -> bool:
+    tree = context.tree
+    if tree is None or not any(
+        isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
+        and node.name == name
+        and node.lineno < factory.lineno
+        and not node.decorator_list
+        for node in tree.body
+    ):
+        return False
+    if not _has_unambiguous_factory_name(tree, name, node_index=context.node_index):
+        return False
+    return not (
+        any(node.id == name and not isinstance(node.ctx, ast.Load) for node in context.nodes(ast.Name))
+        or any(
+            not isinstance(node.ctx, ast.Load) and any(child.id == name for child in nodes(node.value, ast.Name))
+            for node in context.nodes(ast.Attribute, ast.Subscript)
+        )
+        or any(
+            isinstance(node.value, str) and (name in node.value.split(".") or factory.name in node.value.split("."))
+            for node in context.nodes(ast.Constant)
+        )
+        or _provider_escapes(context, name)
+    )
+
+
+def _provider_escapes(context: PythonFileContext, name: str) -> bool:
+    for node in context.nodes(ast.Name):
+        if node.id != name or not isinstance(node.ctx, ast.Load):
+            continue
+        parent = context.parents.get(node)
+        if not (isinstance(parent, ast.arguments) or (isinstance(parent, ast.Call) and parent.func is node)):
+            return True
+    return False