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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.27.5"
+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.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.5 → 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},
+        )
+    )

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

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._closed_helpers import call_matches, closed_references, direct_call, executable_body
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_HELPER = "def _space(match: re.Match[str]) -> str:\n    full = match.group(0)\n    digits = match.group(1)\n    spaced = ' '.join(digits)\n    return full.replace(digits, spaced)\n"
+_BAD = (
+    "import re\nFIRST = re.compile(r'item (\\d+)')\nSECOND = re.compile(r'code (\\d+)')\n"
+    + _HELPER
+    + _HELPER.replace("_space", "_spread")
+    + "FIRST.sub(_space, text)\nSECOND.sub(_spread, text)\n"
+)
+_GOOD = (
+    "import re\nFIRST = re.compile(r'item (\\d+)')\nSECOND = re.compile(r'code (\\d+)')\n"
+    + _HELPER
+    + "FIRST.sub(_space, text)\nSECOND.sub(_space, text)\n"
+)
+_PATTERN_METHODS = frozenset({"sub", "subn", "match", "fullmatch", "search", "findall", "finditer", "split"})
+_SUB_REQUIRED_ARGUMENTS = 2
+
+
+@final
+class DuplicateClosedPureHelper(Rule):
+    id = "duplicate-closed-pure-helper"
+    code = "SARJ489"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Closed private helpers repeat one proven native regex/string transformation.",
+        rationale="Identical private transformations duplicate maintained behavior even when different caller patterns choose the domains in which they run.",
+        remediation="Reuse one existing transformation while keeping each caller's pattern, order and examples. Preserve documented independent versioning or patch contracts explicitly.",
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only undecorated private module-level functions in one authored source file with identical signatures and executable ASTs are compared; no cross-file extraction is suggested.",
+            "The supported pure grammar is one re.Match[str] parameter, straight-line local assignments, immutable literals, native Match.group, str.join and str.replace, and a str result. Defaults and unknown calls are excluded.",
+            "Every reference must be a known direct call or the first replacement argument to Pattern.sub on a stable, unescaped native re.compile binding with a string pattern.",
+            "Escapes, aliases, reflection, rebinding, exports, patch strings, decorators and generated/vendor paths are excluded. Distinct domain docstrings alone do not create runtime behavior; retain useful examples at the surviving owner. No autofix.",
+        ),
+        examples=tuple(
+            RuleExample(
+                example_id=name,
+                title=title,
+                outcome=outcome,
+                files=(ExampleFile.python("app/formatters.py", source),),
+                focus_path=PurePosixPath("app/formatters.py"),
+                expected_count=count,
+                public=True,
+            )
+            for name, title, outcome, source, count in (
+                (
+                    "duplicate-native-transformation",
+                    "Different patterns use identical closed callbacks",
+                    ExampleOutcome.MATCH,
+                    _BAD,
+                    1,
+                ),
+                (
+                    "shared-existing-transformation",
+                    "Patterns retain their choices and share one transformation",
+                    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 ".group" not in context.symbol_source:
+            return []
+        provenance = ResourceProvenance(context)
+        owners: dict[str, ast.FunctionDef] = {}
+        findings: list[Diagnostic] = []
+        for function in tree.body:
+            if (
+                not isinstance(function, ast.FunctionDef)
+                or function.returns is None
+                or not _pure_body(function, context)
+            ):
+                continue
+            references = closed_references(context, function, provenance)
+            if references is None or any(
+                not _known_reference(reference, function, context, provenance) for reference in references
+            ):
+                continue
+            key = (
+                ast.dump(function.args)
+                + ast.dump(function.returns)
+                + ast.dump(ast.Module(body=executable_body(function), type_ignores=[]))
+            )
+            if key not in owners:
+                owners[key] = function
+            elif not is_suppressed(context.source_lines, function.lineno, self.code):
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=function.lineno,
+                        col=function.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=f"`{function.name}` repeats the closed native transformation in `{owners[key].name}`; reuse that helper while preserving caller patterns, useful examples, and intentional independent contracts.",
+                    )
+                )
+        return findings
+
+
+def _pure_body(function: ast.FunctionDef, context: PythonFileContext) -> bool:
+    arguments = [*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs]
+    if (
+        len(arguments) != 1
+        or function.args.defaults
+        or any(function.args.kw_defaults)
+        or not isinstance(function.returns, ast.Name)
+    ):
+        return False
+    if function.returns.id != "str" or not context.imports.builtin_is_unshadowed("str"):
+        return False
+    annotation = arguments[0].annotation
+    if (
+        not isinstance(annotation, ast.Subscript)
+        or context.imports.resolved_qualified_name(annotation.value) != "re.Match"
+        or not isinstance(annotation.slice, ast.Name)
+        or annotation.slice.id != "str"
+    ):
+        return False
+    types = {arguments[0].arg: "match"}
+    body = executable_body(function)
+    if not body or not isinstance(body[-1], ast.Return):
+        return False
+    for statement in body[:-1]:
+        if (
+            not isinstance(statement, ast.Assign)
+            or len(statement.targets) != 1
+            or not isinstance(statement.targets[0], ast.Name)
+        ):
+            return False
+        name = statement.targets[0].id
+        kind = _native_type(statement.value, types)
+        if name in types or kind is None:
+            return False
+        types[name] = kind
+    return body[-1].value is not None and _native_type(body[-1].value, types) == "str"
+
+
+def _native_type(expression: ast.expr, types: dict[str, str]) -> str | None:
+    if isinstance(expression, ast.Name):
+        return types.get(expression.id)
+    if isinstance(expression, ast.Constant):
+        return "str" if isinstance(expression.value, str) else "int" if type(expression.value) is int else None
+    if not isinstance(expression, ast.Call) or expression.keywords or not isinstance(expression.func, ast.Attribute):
+        return None
+    receiver = _native_type(expression.func.value, types)
+    arguments = [_native_type(argument, types) for argument in expression.args]
+    if receiver == "match" and expression.func.attr == "group" and arguments == ["int"]:
+        return "str"
+    if receiver == "str" and (
+        (expression.func.attr == "join" and arguments == ["str"])
+        or (expression.func.attr == "replace" and arguments in (["str", "str"], ["str", "str", "int"]))
+    ):
+        return "str"
+    return None
+
+
+def _known_reference(
+    reference: ast.Name, function: ast.FunctionDef, context: PythonFileContext, provenance: ResourceProvenance
+) -> bool:
+    call = direct_call(reference, context)
+    if call is not None:
+        return call_matches(function, call)
+    parent = context.parents.get(reference)
+    if (
+        not isinstance(parent, ast.Call)
+        or len(parent.args) < _SUB_REQUIRED_ARGUMENTS
+        or parent.args[0] is not reference
+        or not isinstance(parent.func, ast.Attribute)
+        or parent.func.attr != "sub"
+    ):
+        return False
+    return (
+        isinstance(parent.func.value, ast.Name)
+        and _native_pattern(parent.func.value, context, provenance)
+        and not any(isinstance(argument, ast.Starred) for argument in parent.args)
+        and not any(keyword.arg is None for keyword in parent.keywords)
+    )
+
+
+def _native_pattern(receiver: ast.Name, context: PythonFileContext, provenance: ResourceProvenance) -> bool:
+    constructor = provenance.constructor(receiver, receiver)
+    binding = provenance.binding(receiver.id, receiver)
+    if (
+        constructor is None
+        or binding is None
+        or not provenance.imported(constructor.func, "re.compile")
+        or not constructor.args
+    ):
+        return False
+    if not _string_pattern(constructor.args[0], provenance, frozenset()) or any(
+        isinstance(node.value, str)
+        and (receiver.id in node.value.split(".") or node.value in {"re.compile", "re.Match", "re.Pattern"})
+        for node in context.nodes(ast.Constant)
+    ):
+        return False
+    declaration = context.parents.get(binding)
+    if declaration is None or context.parents.get(declaration) is not context.tree or receiver.id in provenance.mutated:
+        return False
+    for read in provenance.reads.get(receiver.id, ()):
+        attribute = context.parents.get(read)
+        use = context.parents.get(attribute) if attribute is not None else None
+        if (
+            provenance.binding(read.id, read) is not binding
+            or not isinstance(attribute, ast.Attribute)
+            or attribute.attr not in _PATTERN_METHODS
+            or not isinstance(use, ast.Call)
+            or use.func is not attribute
+        ):
+            return False
+    return True
+
+
+def _string_pattern(expression: ast.expr, provenance: ResourceProvenance, seen: frozenset[str]) -> bool:
+    if isinstance(expression, ast.Constant):
+        return isinstance(expression.value, str)
+    if isinstance(expression, ast.BinOp) and isinstance(expression.op, ast.Add):
+        return _string_pattern(expression.left, provenance, seen) and _string_pattern(
+            expression.right, provenance, seen
+        )
+    if not isinstance(expression, ast.Name) or expression.id in seen:
+        return False
+    binding = provenance.binding(expression.id, expression)
+    if not isinstance(binding, ast.Name):
+        return False
+    statement = provenance.context.parents.get(binding)
+    if statement is None or provenance.context.parents.get(statement) is not provenance.context.tree:
+        return False
+    value = provenance.assignment_value(binding, expression)
+    return value is not None and _string_pattern(value, provenance, seen | {expression.id})