sarj-python-lint 1.8.3__tar.gz → 1.8.4__tar.gz

{sarj_python_lint-1.8.3 → sarj_python_lint-1.8.4}/PKG-INFO

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

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

{sarj_python_lint-1.8.3 → sarj_python_lint-1.8.4}/src/sarj_python_lint/rules/iac_source_coupled_test.py

@@ -15,14 +15,19 @@ from sarj_python_lint.rule_base import (
     Severity,
 )
 from sarj_python_lint.rules._paths import is_test_path
-from sarj_python_lint.rules.no_raw_source_text_test_oracle import FunctionAnalyzer, top_level_test_functions
+from sarj_python_lint.rules.no_raw_source_text_test_oracle import (
+    IAC_JSON_SOURCE_SUFFIXES,
+    FunctionAnalyzer,
+    module_source_path_tuples,
+    top_level_test_functions,
+)
 
 
 if TYPE_CHECKING:
     from sarj_python_lint._file_context import PythonFileContext
 
 
-IAC_SOURCE_SUFFIXES = (".hcl", ".tf", ".tf.json", ".tfvars", ".tftest.hcl", ".tftest.json")
+IAC_SOURCE_SUFFIXES = (".hcl", ".tf", ".tfvars", ".tftest.hcl", *IAC_JSON_SOURCE_SUFFIXES)
 
 
 @final
@@ -42,7 +47,7 @@ class IacSourceCoupledTest(Rule):
         ),
         category=RuleCategory.TESTING,
         limitations=(
-            "The rule follows local aliases, path collections, context-managed reads, and common normalization; interprocedural flows remain unreported.",
+            "The rule follows local aliases, path collections, context-managed reads, common normalization, and direct comprehension reads unpacked from stable module-level path tuples; interprocedural flows remain unreported.",
             "Files produced beneath recognized temporary-directory fixtures are generated outputs and remain unreported.",
             "The Python detector currently owns Terraform and HCL suffixes; YAML remains with the general source-coupled rule.",
             "Fixture, golden, and snapshot paths are treated as deliberate representation contracts; other packaging, formatter, and compatibility contracts require an exact suppression.",
@@ -93,11 +98,13 @@ class IacSourceCoupledTest(Rule):
             return []
         imports = context.module_imports
         source_lines = context.source_lines
+        module_tuples = module_source_path_tuples(tree, imports, IAC_SOURCE_SUFFIXES)
         assertions = [
             assertion
             for function, unittest_style in top_level_test_functions(tree, imports)
             for assertion in FunctionAnalyzer(
                 IAC_SOURCE_SUFFIXES,
+                module_path_tuples=module_tuples,
                 imports=imports,
                 suppression_code=self.code,
                 suppression_lines=source_lines,

{sarj_python_lint-1.8.3 → sarj_python_lint-1.8.4}/src/sarj_python_lint/rules/no_raw_source_text_test_oracle.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import ast
+from collections import Counter
 from dataclasses import dataclass
 from pathlib import PurePosixPath
+from types import MappingProxyType
 from typing import TYPE_CHECKING, ClassVar, NamedTuple, final, override
 
 from sarj_python_lint.rule_base import (
@@ -23,6 +25,8 @@ from sarj_python_lint.rules._paths import is_test_path
 
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator, Mapping
+
     from sarj_python_lint._file_context import PythonFileContext
 
 
@@ -35,6 +39,7 @@ GENERAL_SOURCE_SUFFIXES = (
     ".mjs",
     ".py",
     ".sh",
+    ".sh.tftpl",
     ".sql",
     ".toml",
     ".ts",
@@ -43,6 +48,11 @@ GENERAL_SOURCE_SUFFIXES = (
     ".yml",
 )
 
+GENERAL_SOURCE_BASENAMES = frozenset({"Dockerfile"})
+IAC_JSON_SOURCE_SUFFIXES = (".tf.json", ".tftest.json")
+
+_EMPTY_PATH_TUPLES: Mapping[str, int] = MappingProxyType({})
+
 _REPRESENTATION_DIRS = frozenset({"fixture", "fixtures", "golden", "goldens", "snapshot", "snapshots"})
 _PYTEST = frozenset({"pytest"})
 _UNITTEST = frozenset({"unittest"})
@@ -59,12 +69,25 @@ class _ApiProvenance:
     shadowed: frozenset[str]
 
 
+@dataclass(frozen=True, slots=True)
+class _SourceKinds:
+    suffixes: tuple[str, ...]
+    basenames: frozenset[str] = frozenset()
+
+    def matches(self, value: str) -> bool:
+        lowered = value.lower()
+        for suffix in IAC_JSON_SOURCE_SUFFIXES:
+            if lowered.endswith(suffix):
+                return suffix in self.suffixes
+        return lowered.endswith(self.suffixes) or value.replace("\\", "/").rsplit("/", 1)[-1] in self.basenames
+
+
 @dataclass(frozen=True, slots=True)
 class _TextFlow:
     raw_names: set[str]
     path_names: set[str]
     ephemeral_path_names: set[str]
-    source_suffixes: tuple[str, ...]
+    sources: _SourceKinds
     api: _ApiProvenance
 
 
@@ -123,7 +146,9 @@ class NoRawSourceTextTestOracle(Rule):
         autofix=AutofixPolicy.NONE,
         aliases=("source-coupled-test",),
         limitations=(
-            "The rule follows local aliases, path aliases, context-managed reads, and common text normalization from source-like code or configuration suffixes; interprocedural flows remain unreported.",
+            "The rule recognizes source-like suffixes, shell templates ending in .sh.tftpl, and the exact Dockerfile basename; it follows local aliases, context-managed reads, and common normalization.",
+            "Direct generator/list-comprehension reads unpacked from stable module-level path tuples are followed; mutable collections, rebinding, filtered comprehensions, and interprocedural flows remain unreported.",
+            "Literal shebang startswith checks are representation contracts and remain unreported; other text compatibility sentinels require an exact suppression.",
             "Files produced beneath recognized temporary-directory fixtures are generated artifacts, not repository source, and remain unreported.",
             "Paths beneath fixture, golden, and snapshot directories are treated as deliberate representation contracts and remain unreported.",
             "When raw representation is genuinely the contract (for example a golden or compatibility sentinel), use an exact line suppression with the reason.",
@@ -171,11 +196,16 @@ class NoRawSourceTextTestOracle(Rule):
             return []
         imports = context.module_imports
         source_lines = context.source_lines
+        module_tuples = module_source_path_tuples(
+            tree, imports, GENERAL_SOURCE_SUFFIXES, source_basenames=GENERAL_SOURCE_BASENAMES
+        )
         assertions = [
             assertion
             for function, unittest_style in top_level_test_functions(tree, imports)
             for assertion in FunctionAnalyzer(
                 GENERAL_SOURCE_SUFFIXES,
+                source_basenames=GENERAL_SOURCE_BASENAMES,
+                module_path_tuples=module_tuples,
                 imports=imports,
                 suppression_code=self.code,
                 suppression_lines=source_lines,
@@ -361,7 +391,8 @@ def _node_is_suppressed(source_lines: list[str], node: ast.AST, code: str) -> bo
 
 class FunctionAnalyzer(ast.NodeVisitor):
     _imports: ImportIndex | None
-    _source_suffixes: tuple[str, ...]
+    _module_path_tuples: Mapping[str, int]
+    _sources: _SourceKinds
     _suppression_code: str | None
     _suppression_lines: list[str] | None
     _unittest_style: bool
@@ -370,12 +401,15 @@ class FunctionAnalyzer(ast.NodeVisitor):
         self,
         source_suffixes: tuple[str, ...],
         *,
+        source_basenames: frozenset[str] = frozenset(),
+        module_path_tuples: Mapping[str, int] = _EMPTY_PATH_TUPLES,
         imports: ImportIndex | None = None,
         suppression_code: str | None = None,
         suppression_lines: list[str] | None = None,
         unittest_style: bool = False,
     ) -> None:
-        self._source_suffixes = source_suffixes
+        self._sources = _SourceKinds(source_suffixes, source_basenames)
+        self._module_path_tuples = module_path_tuples
         self._unittest_style = unittest_style
         self._imports = imports
         self._suppression_code = suppression_code
@@ -439,7 +473,7 @@ class FunctionAnalyzer(ast.NodeVisitor):
             if item.optional_vars is not None:
                 self._clear_target(item.optional_vars)
             if isinstance(item.optional_vars, ast.Name) and _is_source_open(
-                item.context_expr, self._paths, self._ephemeral_paths, self._source_suffixes, self._provenance
+                item.context_expr, self._paths, self._ephemeral_paths, self._sources, self._provenance
             ):
                 self._raw.add(item.optional_vars.id)
                 self._raw_origins[item.optional_vars.id] = {item.context_expr.lineno}
@@ -569,19 +603,56 @@ class FunctionAnalyzer(ast.NodeVisitor):
 
     def _record_target(self, target: ast.expr, value: ast.expr) -> None:
         self._clear_target(target)
+        if isinstance(target, ast.Tuple | ast.List):
+            self._record_unpacked_read(target, value)
+            return
         if not isinstance(target, ast.Name):
             return
         raw_origins = _expression_origins(value, self._raw_origins, self._flow)
         if _ephemeral_path_expression(value, self._ephemeral_paths):
             self._ephemeral_paths.add(target.id)
-        if _source_path_collection(value, self._paths, self._source_suffixes, self._provenance):
+        if _source_path_collection(value, self._paths, self._sources, self._provenance):
             self._collections.add(target.id)
-        if _source_path_expression(value, self._paths, self._source_suffixes, self._provenance):
+        if _source_path_expression(value, self._paths, self._sources, self._provenance):
             self._paths.add(target.id)
         if _raw_text_expression(value, self._flow):
             self._raw.add(target.id)
             self._raw_origins[target.id] = raw_origins or {value.lineno}
 
+    def _record_unpacked_read(self, target: ast.Tuple | ast.List, value: ast.expr) -> None:
+        if not isinstance(value, ast.GeneratorExp | ast.ListComp) or len(value.generators) != 1:
+            return
+        generator = value.generators[0]
+        if (
+            generator.is_async
+            or generator.ifs
+            or not isinstance(generator.target, ast.Name)
+            or not isinstance(generator.iter, ast.Name)
+        ):
+            return
+        if (
+            generator.iter.id in self._provenance.shadowed
+            or self._module_path_tuples.get(generator.iter.id) != len(target.elts)
+            or not all(isinstance(element, ast.Name) for element in target.elts)
+            or any(isinstance(child, ast.NamedExpr) for child in walk_ast(value.elt))
+        ):
+            return
+        flow = _TextFlow(
+            self._raw - {generator.target.id},
+            self._paths | {generator.target.id},
+            self._ephemeral_paths - {generator.target.id},
+            self._sources,
+            _ApiProvenance(self._provenance.imports, self._provenance.shadowed | {generator.target.id}),
+        )
+        if not _raw_text_expression(value.elt, flow):
+            return
+        raw_origins = {name: origins for name, origins in self._raw_origins.items() if name != generator.target.id}
+        origins = _expression_origins(value.elt, raw_origins, flow) or {value.elt.lineno}
+        for element in target.elts:
+            if isinstance(element, ast.Name):
+                self._raw.add(element.id)
+                self._raw_origins[element.id] = set(origins)
+
     def _clear_target(self, target: ast.expr) -> None:
         for child in walk_ast(target):
             if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store):
@@ -630,7 +701,7 @@ class FunctionAnalyzer(ast.NodeVisitor):
             self._raw,
             self._paths,
             self._ephemeral_paths,
-            self._source_suffixes,
+            self._sources,
             self._provenance,
         )
 
@@ -646,30 +717,90 @@ def _intersect_flow_states(left: _FlowState, right: _FlowState) -> _FlowState:
     )
 
 
-def _function_bound_names(function: ast.FunctionDef | ast.AsyncFunctionDef) -> frozenset[str]:
-    args = function.args
-    names = {
-        argument.arg
-        for argument in (*args.posonlyargs, *args.args, *args.kwonlyargs, args.vararg, args.kwarg)
-        if argument is not None
-    }
-    pending: list[ast.AST] = list(function.body)
+def module_source_path_tuples(
+    tree: ast.Module,
+    imports: ImportIndex,
+    source_suffixes: tuple[str, ...],
+    *,
+    source_basenames: frozenset[str] = frozenset(),
+) -> dict[str, int]:
+    sources = _SourceKinds(source_suffixes, source_basenames)
+    api = _ApiProvenance(imports, frozenset())
+    tuples: dict[str, int] = {}
+    for statement in tree.body:
+        match statement:
+            case ast.Assign(targets=[target], value=value) | ast.AnnAssign(target=target, value=value):
+                pass
+            case _:
+                continue
+        if (
+            isinstance(target, ast.Name)
+            and isinstance(value, ast.Tuple)
+            and _source_path_collection(value, set(), sources, api)
+        ):
+            tuples[target.id] = len(value.elts)
+    if not tuples:
+        return {}
+    bindings = Counter(_enclosing_scope_bindings(tree.body))
+    if bindings["*"]:
+        return {}
+    global_names = {name for node in walk_ast(tree) if isinstance(node, ast.Global) for name in node.names}
+    return {name: size for name, size in tuples.items() if bindings[name] == 1 and name not in global_names}
+
+
+def _enclosing_scope_bindings(nodes: list[ast.stmt]) -> Iterator[str]:
+    pending: list[ast.AST] = list(nodes)
     while pending:
         current = pending.pop()
         match current:
             case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef():
-                names.add(current.name)
+                yield current.name
+                pending.extend(_definition_enclosing_expressions(current))
                 continue
-            case ast.Lambda() | ast.ListComp() | ast.SetComp() | ast.DictComp() | ast.GeneratorExp():
+            case ast.Lambda():
+                pending.extend(_definition_enclosing_expressions(current))
+                continue
+            case ast.ListComp() | ast.SetComp() | ast.DictComp() | ast.GeneratorExp():
+                pending.extend(child.target for child in walk_ast(current) if isinstance(child, ast.NamedExpr))
                 continue
             case ast.Import(names=aliases) | ast.ImportFrom(names=aliases):
-                names.update(alias.asname or alias.name.partition(".")[0] for alias in aliases)
+                yield from (alias.asname or alias.name.partition(".")[0] for alias in aliases)
                 continue
-            case ast.Name(id=name, ctx=(ast.Store() | ast.Del())):
-                names.add(name)
+            case (
+                ast.Name(id=name, ctx=(ast.Store() | ast.Del()))
+                | ast.ExceptHandler(name=str(name))
+                | ast.MatchAs(name=str(name))
+                | ast.MatchStar(name=str(name))
+                | ast.MatchMapping(rest=str(name))
+            ):
+                yield name
             case _:
                 pass
         pending.extend(ast.iter_child_nodes(current))
+
+
+def _definition_enclosing_expressions(
+    node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda,
+) -> list[ast.AST]:
+    if isinstance(node, ast.ClassDef):
+        return [*node.decorator_list, *node.bases, *node.keywords]
+    defaults: list[ast.AST] = [
+        *node.args.defaults,
+        *(default for default in node.args.kw_defaults if default is not None),
+    ]
+    if isinstance(node, ast.Lambda):
+        return defaults
+    return [*node.decorator_list, *defaults]
+
+
+def _function_bound_names(function: ast.FunctionDef | ast.AsyncFunctionDef) -> frozenset[str]:
+    args = function.args
+    names = {
+        argument.arg
+        for argument in (*args.posonlyargs, *args.args, *args.kwonlyargs, args.vararg, args.kwarg)
+        if argument is not None
+    }
+    names.update(_enclosing_scope_bindings(function.body))
     return frozenset(names)
 
 
@@ -695,7 +826,7 @@ def _is_source_open(
     node: ast.expr,
     path_names: set[str],
     ephemeral_path_names: set[str],
-    source_suffixes: tuple[str, ...],
+    sources: _SourceKinds,
     api: _ApiProvenance,
 ) -> bool:
     if not isinstance(node, ast.Call):
@@ -715,7 +846,7 @@ def _is_source_open(
             path = node.func.value
     else:
         return False
-    return _source_path_expression(path, path_names, source_suffixes, api) and not _ephemeral_path_expression(
+    return _source_path_expression(path, path_names, sources, api) and not _ephemeral_path_expression(
         path, ephemeral_path_names
     )
 
@@ -723,7 +854,7 @@ def _is_source_open(
 def _source_path_expression(
     node: ast.AST,
     path_names: set[str],
-    source_suffixes: tuple[str, ...],
+    sources: _SourceKinds,
     api: _ApiProvenance,
 ) -> bool:
     if _representation_fixture_path(node):
@@ -732,31 +863,31 @@ def _source_path_expression(
         case ast.Name(id=name):
             return name in path_names
         case ast.Constant(value=str(value)):
-            return value.lower().endswith(source_suffixes)
+            return sources.matches(value)
         case ast.Attribute(attr="__file__"):
-            return ".py" in source_suffixes
+            return ".py" in sources.suffixes
         case ast.Call(func=function, args=[path, *_]) if _api_resolves(
             function, api, sources=frozenset({"pathlib"}), symbol="Path"
         ):
-            return _source_path_expression(path, path_names, source_suffixes, api)
+            return _source_path_expression(path, path_names, sources, api)
         case ast.Call(func=function) if _api_resolves(function, api, sources=frozenset({"inspect"}), symbol="getfile"):
-            return ".py" in source_suffixes
+            return ".py" in sources.suffixes
         case ast.JoinedStr(values=values):
-            return any(_source_path_expression(value, path_names, source_suffixes, api) for value in values)
+            return any(_source_path_expression(value, path_names, sources, api) for value in values)
         case ast.Call(
             func=ast.Attribute(value=receiver, attr="with_suffix" | "with_name"),
             args=[ast.Constant(value=str(value)), *_],
         ):
-            return value.lower().endswith(source_suffixes) and (
-                _source_path_expression(receiver, path_names, source_suffixes, api)
+            return sources.matches(value) and (
+                _source_path_expression(receiver, path_names, sources, api)
                 or (
                     isinstance(receiver, ast.Call)
                     and _api_resolves(receiver.func, api, sources=frozenset({"pathlib"}), symbol="Path")
                 )
             )
         case ast.BinOp(left=left, right=right):
-            return _source_path_expression(left, path_names, source_suffixes, api) or _source_path_expression(
-                right, path_names, source_suffixes, api
+            return _source_path_expression(left, path_names, sources, api) or _source_path_expression(
+                right, path_names, sources, api
             )
         case ast.Subscript(value=ast.Name(id=name)):
             return name in path_names
@@ -781,13 +912,13 @@ def _ephemeral_path_expression(node: ast.AST, ephemeral_path_names: set[str]) ->
 def _source_path_collection(
     node: ast.AST,
     path_names: set[str],
-    source_suffixes: tuple[str, ...],
+    sources: _SourceKinds,
     api: _ApiProvenance,
 ) -> bool:
     return (
         isinstance(node, (ast.List, ast.Set, ast.Tuple))
         and bool(node.elts)
-        and all(_source_path_expression(element, path_names, source_suffixes, api) for element in node.elts)
+        and all(_source_path_expression(element, path_names, sources, api) for element in node.elts)
     )
 
 
@@ -795,19 +926,17 @@ def _raw_source_read(
     node: ast.expr,
     path_names: set[str],
     ephemeral_path_names: set[str],
-    source_suffixes: tuple[str, ...],
+    sources: _SourceKinds,
     api: _ApiProvenance,
 ) -> bool:
     if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
         return False
     supported_reads = {"read_bytes", "read_text"}
     if node.func.attr in supported_reads:
-        return _source_path_expression(
-            node.func.value, path_names, source_suffixes, api
-        ) and not _ephemeral_path_expression(node.func.value, ephemeral_path_names)
-    return node.func.attr == "read" and _is_source_open(
-        node.func.value, path_names, ephemeral_path_names, source_suffixes, api
-    )
+        return _source_path_expression(node.func.value, path_names, sources, api) and not _ephemeral_path_expression(
+            node.func.value, ephemeral_path_names
+        )
+    return node.func.attr == "read" and _is_source_open(node.func.value, path_names, ephemeral_path_names, sources, api)
 
 
 def _raw_text_expression(
@@ -816,7 +945,7 @@ def _raw_text_expression(
 ) -> bool:
     if isinstance(node, ast.Name):
         return node.id in flow.raw_names
-    if _raw_source_read(node, flow.path_names, flow.ephemeral_path_names, flow.source_suffixes, flow.api):
+    if _raw_source_read(node, flow.path_names, flow.ephemeral_path_names, flow.sources, flow.api):
         return True
     if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
         handle_reads = {"read", "readlines"}
@@ -837,13 +966,30 @@ def _raw_text_oracle(
     if _is_raw_text_iteration_call(node, flow):
         return True
     if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
-        if node.func.attr in _TEXT_ASSERTIONS and _raw_text_expression(node.func.value, flow):
+        if (
+            node.func.attr in _TEXT_ASSERTIONS
+            and not _is_shebang_contract(node)
+            and _raw_text_expression(node.func.value, flow)
+        ):
             return True
         if node.func.attr in _REGEX_ASSERTIONS and any(_raw_text_expression(argument, flow) for argument in node.args):
             return True
     return any(_raw_text_oracle(child, flow) for child in ast.iter_child_nodes(node) if isinstance(child, ast.expr))
 
 
+def _is_shebang_contract(node: ast.Call) -> bool:
+    return (
+        isinstance(node.func, ast.Attribute)
+        and node.func.attr == "startswith"
+        and not node.keywords
+        and len(node.args) == 1
+        and isinstance(node.args[0], ast.Constant)
+        and isinstance(node.args[0].value, str)
+        and node.args[0].value.startswith("#!")
+        and len(node.args[0].value.splitlines()) == 1
+    )
+
+
 def _raw_text_measurement(
     node: ast.expr,
     flow: _TextFlow,
@@ -910,7 +1056,7 @@ def _expression_origins(
         if isinstance(child, ast.Name):
             origins.update(raw_origins.get(child.id, set()))
         elif isinstance(child, ast.Call) and _raw_source_read(
-            child, flow.path_names, flow.ephemeral_path_names, flow.source_suffixes, flow.api
+            child, flow.path_names, flow.ephemeral_path_names, flow.sources, flow.api
         ):
             origins.add(child.lineno)
     return origins