sarj-python-lint 1.64.0__tar.gz → 1.66.1__tar.gz

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/.gitignore

@@ -44,6 +44,9 @@ Thumbs.db
 !.claude/skills/test-value/
 .claude/skills/test-value/*
 !.claude/skills/test-value/SKILL.md
+!.claude/skills/100-passes/
+.claude/skills/100-passes/*
+!.claude/skills/100-passes/SKILL.md
 apps/docs/.wrangler/
 apps/docs/.dev.vars*
 !apps/docs/.dev.vars.example

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/PKG-INFO

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

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

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/_file_context.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, final
 
 from sarj_python_lint._analysis_session import AnalysisSession
 from sarj_python_lint._source import symbol_prefilter_source
+from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics
 from sarj_python_lint.rules._ast_index import NodeIndex
 from sarj_python_lint.rules._fastapi import FastapiIndex
 from sarj_python_lint.rules._imports import ImportIndex
@@ -18,6 +19,7 @@ if TYPE_CHECKING:
     from pathlib import Path
 
     from sarj_python_lint.rules._copy_on_write import CopyOnWriteAnalysis
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
     from sarj_python_lint.rules._test_provenance import TestProvenance
 
 
@@ -91,6 +93,10 @@ class PythonFileContext:
     def module_imports(self) -> ImportIndex:
         return ImportIndex.from_tree(self._valid_tree(), module_scope_only=True)
 
+    @cached_property
+    def annotation_semantics(self) -> AnnotationSemantics:
+        return AnnotationSemantics.from_imports(self._valid_tree(), self.module_imports)
+
     @cached_property
     def dynamic_namespace(self) -> bool:
         return dynamic_namespace_access(self.nodes(ast.AST), self.imports, self.parents)
@@ -117,3 +123,16 @@ class PythonFileContext:
         from sarj_python_lint.rules._copy_on_write import CopyOnWriteAnalysis  # ruff: ignore[import-outside-top-level] — share ownership analysis only when requested
 
         return CopyOnWriteAnalysis(self)
+
+    @cached_property
+    def resource_provenance(self) -> ResourceProvenance:
+        from sarj_python_lint.rules._resource_provenance import ResourceProvenance  # ruff: ignore[import-outside-top-level] -- file-owned binding facts are lazy.
+
+        # The owner caches this analysis; borrowing prevents a reference cycle.
+        return ResourceProvenance(self, borrow_context=True)
+
+    @cached_property
+    def static_resource_provenance(self) -> ResourceProvenance:
+        from sarj_python_lint.rules._resource_provenance import ResourceProvenance  # ruff: ignore[import-outside-top-level] -- keep static-namespace policy in a separate cached analysis.
+
+        return ResourceProvenance(self, require_static_namespace=True, borrow_context=True)

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/cast_access.py

@@ -6,13 +6,14 @@ from typing import TYPE_CHECKING, Literal
 
 from sarj_python_lint._file_context import PythonFileContext
 from sarj_python_lint.rules._namespace_access import dynamic_namespace_access
-from sarj_python_lint.rules._resource_provenance import ResourceProvenance
 
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
     from pathlib import Path
 
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
 
 _TYPING = frozenset({"typing", "typing_extensions"})
 _GETATTR_ARITIES = frozenset({2, 3})
@@ -44,7 +45,7 @@ def indirect_typing_cast_accesses(path: Path, source: str) -> tuple[CastAccess,
 
 
 def _reflection_accesses(context: PythonFileContext) -> list[CastAccess]:
-    provenance = ResourceProvenance(context)
+    provenance = context.resource_provenance
     candidates = [
         (node, receiver)
         for node in context.nodes(ast.Call, ast.Subscript)

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_annotation_semantics.py

@@ -19,7 +19,10 @@ class AnnotationSemantics:
 
     @classmethod
     def from_tree(cls, tree: ast.Module, *, module_scope_only: bool = True) -> Self:
-        imports = ImportIndex.from_tree(tree, module_scope_only=module_scope_only)
+        return cls.from_imports(tree, ImportIndex.from_tree(tree, module_scope_only=module_scope_only))
+
+    @classmethod
+    def from_imports(cls, tree: ast.Module, imports: ImportIndex) -> Self:
         candidates: dict[str, ast.expr] = {}
         ambiguous: set[str] = set()
         for statement in tree.body:

sarj_python_lint-1.66.1/src/sarj_python_lint/rules/_ast_names.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import ast
+
+
+def root_name(node: ast.expr) -> str | None:
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return node.id if isinstance(node, ast.Name) else None
+
+
+def expression_root(node: ast.expr) -> str | None:
+    while isinstance(node, (ast.Attribute, ast.Subscript)):
+        node = node.value
+    return node.id if isinstance(node, ast.Name) else None
+
+
+def terminal_name(node: ast.expr) -> str | None:
+    match node:
+        case ast.Name(id=name) | ast.Attribute(attr=name):
+            return name
+        case _:
+            return None
+
+
+def unqualified_name(node: ast.expr) -> str:
+    match node:
+        case ast.Name(id=name) | ast.Attribute(attr=name):
+            return name
+        case _:
+            return ""
+
+
+def dotted_parts(node: ast.expr) -> tuple[str, ...] | None:
+    parts: list[str] = []
+    current = node
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+    if not isinstance(current, ast.Name):
+        return None
+    parts.append(current.id)
+    return tuple(reversed(parts))
+
+
+def dotted_name(node: ast.expr) -> str | None:
+    parts = dotted_parts(node)
+    return ".".join(parts) if parts is not None else None
+
+
+def assignment_names(node: ast.AST) -> set[str]:
+    match node:
+        case ast.Name(id=name):
+            return {name}
+        case ast.Tuple() | ast.List():
+            names: set[str] = set()
+            for element in node.elts:
+                names.update(assignment_names(element))
+            return names
+        case ast.Starred(value=value):
+            return assignment_names(value)
+        case _:
+            return set()

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_closed_helpers.py

@@ -183,3 +183,13 @@ def _plain_decorator(
         and not (keyword.arg == "mode" and isinstance(keyword.value, ast.Constant) and keyword.value.value == "wrap")
         for keyword in decorator.keywords
     )
+
+
+def closed_owner(function: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext) -> bool:
+    if not isinstance(function, ast.FunctionDef) or not function.name.startswith("_"):
+        return False
+    references = closed_references(context, function, context.resource_provenance)
+    return bool(references) and all(
+        (call := direct_call(reference, context)) is not None and call_matches(function, call)
+        for reference in references
+    )

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_comments.py

@@ -326,7 +326,13 @@ class _Scan(NamedTuple):
     ordered: _Ordered
 
 
-_last_scan: tuple[str, _Scan] | None = None
+class _ScanMemo(NamedTuple):
+    source: str
+    scan: _Scan | None
+    comment_lines: frozenset[int] | None
+
+
+_last_scan: _ScanMemo | None = None
 
 
 def all_comments(source: str) -> _CommentScan[_Ordered]:
@@ -334,15 +340,35 @@ def all_comments(source: str) -> _CommentScan[_Ordered]:
     return _CommentScan(scan.ordered, scan.first_code_line)
 
 
+def comment_line_numbers(source: str) -> frozenset[int]:
+    global _last_scan  # ruff: ignore[global-statement] -- retain the existing single-source memo for both comment projections.
+    cached = _last_scan
+    scan = cached.scan if cached is not None and cached.source is source else None
+    if cached is not None and cached.source is source and cached.comment_lines is not None:
+        return cached.comment_lines
+    lines: frozenset[int]
+    if scan is not None:
+        lines = frozenset(comment.line for comment in scan.ordered)
+    else:
+        try:
+            tokens = tokenize.generate_tokens(io.StringIO(source).readline)
+            lines = frozenset(token.start[0] for token in tokens if token.type == tokenize.COMMENT)
+        except IndentationError, tokenize.TokenError:
+            lines = frozenset()
+    _last_scan = _ScanMemo(source, scan, lines)
+    return lines
+
+
 def _scan_memo(source: str) -> _Scan:
     global _last_scan  # ruff: ignore[global-statement] — single-slot memo; the CLI runs rules per file sequentially
-    if _last_scan is not None and _last_scan[0] is source:
-        return _last_scan[1]
+    cached = _last_scan if _last_scan is not None and _last_scan.source is source else None
+    if cached is not None and cached.scan is not None:
+        return cached.scan
     try:
         result = _scan(source)
     except UnicodeError:
         result = _Scan([], [], set(), 1 << 30, [])
-    _last_scan = (source, result)
+    _last_scan = _ScanMemo(source, result, cached.comment_lines if cached is not None else None)
     return result
 
 

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_copy_on_write.py

@@ -110,9 +110,7 @@ class _Models:
     def validation_owner(self, unit: SourceUnit) -> _ValidationOwner:
         if unit.path not in self._validation_owners:
             context = PythonFileContext(unit.path, unit.source, self._validation_session)
-            self._validation_owners[unit.path] = _ValidationOwner(
-                context, ResourceProvenance(context, require_static_namespace=True)
-            )
+            self._validation_owners[unit.path] = _ValidationOwner(context, context.static_resource_provenance)
         return self._validation_owners[unit.path]
 
     def annotations(self, unit: SourceUnit) -> AnnotationSemantics:
@@ -378,7 +376,7 @@ class CopyOnWriteAnalysis:
 
     @cached_property
     def _validator_provider(self) -> ResourceProvenance:
-        return ResourceProvenance(self.context, require_static_namespace=True)
+        return self.context.static_resource_provenance
 
     def _function(self, function: _Function) -> None:
         parameters = [*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs]

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_data_union_discriminator.py

@@ -72,6 +72,7 @@ def data_union_diagnostics(context: PythonFileContext, code: str) -> list[Diagno
 class _DataUnions:
     def __init__(self, context: PythonFileContext, tree: ast.Module) -> None:
         self.context = context
+        # This analysis refines mutation ownership; keep its provenance private.
         self.provenance = ResourceProvenance(context, require_static_namespace=True)
         self.provenance.mutated = _scoped_module_mutations(self.provenance, tree)
         bindings = self.provenance.bindings.get(tree, {})

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_docstrings.py

@@ -13,9 +13,16 @@ if TYPE_CHECKING:
     from collections.abc import Iterable
 
     from sarj_python_lint.rules._ast_index import NodeIndex
+    from sarj_python_lint.rules._imports import ImportIndex
 
 
 _GETATTR_MIN_ARGS = 2
+_RUNTIME_DOC_DECORATORS = (
+    (frozenset({"agents"}), "function_tool"),
+    (frozenset({"click"}), "command"),
+    (frozenset({"typer"}), "command"),
+)
+_OVERLOAD_MODULES = frozenset({"typing", "typing_extensions"})
 
 # Docstring filler that says nothing about *which* thing is being described.
 _BASE_STOPWORDS = frozenset(
@@ -259,6 +266,18 @@ def decorator_markers(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDe
     return markers
 
 
+def is_runtime_consumed_or_overload(node: ast.FunctionDef | ast.AsyncFunctionDef, imports: ImportIndex) -> bool:
+    if decorator_markers(node) & PROMPT_DECORATOR_MARKERS:
+        return True
+    for decorator in node.decorator_list:
+        target = decorator.func if isinstance(decorator, ast.Call) else decorator
+        if imports.resolves(target, sources=_OVERLOAD_MODULES, symbol="overload"):
+            return True
+        if any(imports.resolves(target, sources=sources, symbol=symbol) for sources, symbol in _RUNTIME_DOC_DECORATORS):
+            return True
+    return False
+
+
 def docstring_expression(
     node: ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
 ) -> ast.Expr | None:

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_pydantic_field_contract.py

@@ -13,11 +13,11 @@ from sarj_python_lint.json_boundary import is_object_mapping
 from sarj_python_lint.rules._first_party import distribution_root
 from sarj_python_lint.rules._namespace_access import dynamic_namespace_access
 from sarj_python_lint.rules._native_namespace_capability import native_namespace_capability_escapes
-from sarj_python_lint.rules._resource_provenance import ResourceProvenance
 
 
 if TYPE_CHECKING:
     from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
 
 
 MODEL_SOURCES = frozenset({"pydantic", "pydantic.main"})
@@ -43,7 +43,7 @@ def direct_models(context: PythonFileContext, *, methods: bool = False) -> tuple
         or dynamic_namespace_access(context.nodes(ast.AST), context.imports, context.parents)
     ):
         return ()
-    provenance = ResourceProvenance(context, require_static_namespace=True)
+    provenance = context.static_resource_provenance
     return tuple(
         node
         for node in tree.body

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_resource_provenance.py

@@ -5,9 +5,9 @@ from collections import defaultdict
 from functools import cached_property
 from types import MappingProxyType
 from typing import TYPE_CHECKING, final
+from weakref import ReferenceType, ref
 
 from sarj_python_lint.rules._ast_index import has_own_yield
-from sarj_python_lint.rules._namespace_access import dynamic_namespace_access
 from sarj_python_lint.rules._runtime_bindings import RuntimeBindings
 
 
@@ -71,8 +71,13 @@ def builtin_namespace_untouched(context: PythonFileContext) -> bool:
 
 @final
 class ResourceProvenance:
-    def __init__(self, context: PythonFileContext, *, require_static_namespace: bool = False) -> None:
-        self.context = context
+    def __init__(
+        self, context: PythonFileContext, *, require_static_namespace: bool = False, borrow_context: bool = False
+    ) -> None:
+        self._context: PythonFileContext | ReferenceType[PythonFileContext] = (
+            ref(context) if borrow_context else context
+        )
+        self.parents = context.parents
         self.require_static_namespace = require_static_namespace
         self.bindings: dict[ast.AST | None, dict[str, list[ast.AST]]] = defaultdict(lambda: defaultdict(list))
         self.reads: dict[str, list[ast.Name]] = defaultdict(list)
@@ -98,15 +103,23 @@ class ResourceProvenance:
                 if root is not None:
                     self.mutated.add(root)
 
+    @property
+    def context(self) -> PythonFileContext:
+        context = self._context() if isinstance(self._context, ReferenceType) else self._context
+        if context is None:
+            msg = "The provenance file context has been released"
+            raise ReferenceError(msg)
+        return context
+
     @cached_property
     def builtin_namespace_untouched(self) -> bool:
         return builtin_namespace_untouched(self.context)
 
     def scope(self, node: ast.AST) -> ast.AST | None:
-        parent = self.context.parents.get(node)
+        parent = self.parents.get(node)
         while parent is not None:
             if isinstance(parent, ast.arguments) and (node in parent.defaults or node in parent.kw_defaults):
-                parent = self.context.parents.get(parent)
+                parent = self.parents.get(parent)
             elif isinstance(parent, _SCOPES) and not (
                 (
                     isinstance(parent, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef)
@@ -118,12 +131,12 @@ class ResourceProvenance:
             if parent is None:
                 return None
             node = parent
-            parent = self.context.parents.get(parent)
+            parent = self.parents.get(parent)
         return None
 
     def _binding_scope(self, node: ast.AST) -> ast.AST | None:
         scope = self.scope(node)
-        parent = self.context.parents.get(node)
+        parent = self.parents.get(node)
         if isinstance(parent, ast.NamedExpr) and parent.target is node:
             while isinstance(scope, ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp):
                 scope = self.scope(scope)
@@ -155,7 +168,7 @@ class ResourceProvenance:
         binding = self.runtime_binding(root, node)
         if not isinstance(binding, ast.alias):
             return None
-        qualified = import_name_for_binding(node, binding, self.context.parents.get(binding))
+        qualified = import_name_for_binding(node, binding, self.parents.get(binding))
         if qualified is None or not self._owner_namespace_untouched(qualified.partition(".")[0]):
             return None
         if binding not in self.runtime_import_cache:
@@ -195,7 +208,7 @@ class ResourceProvenance:
     def _namespace_aliases(self) -> dict[str, tuple[ast.alias, ...]]:
         aliases: dict[str, list[ast.alias]] = defaultdict(list)
         for binding in self.context.nodes(ast.alias):
-            parent = self.context.parents.get(binding)
+            parent = self.parents.get(binding)
             name = binding.asname or (
                 binding.name.partition(".")[0] if isinstance(parent, ast.Import) else binding.name
             )
@@ -231,7 +244,7 @@ class ResourceProvenance:
         return paths
 
     def _namespace_module_path(self, binding: ast.alias, attributes: tuple[str, ...]) -> Path | None:
-        parent = self.context.parents.get(binding)
+        parent = self.parents.get(binding)
         match parent:
             case ast.Import():
                 prefix = binding.name if binding.asname else binding.name.partition(".")[0]
@@ -250,7 +263,7 @@ class ResourceProvenance:
         for node in nodes:
             if not isinstance(node, ast.alias):
                 return False
-            parent = self.context.parents.get(node)
+            parent = self.parents.get(node)
             if isinstance(parent, ast.Import):
                 targets.add(("import", None, 0, node.name))
             elif isinstance(parent, ast.ImportFrom):
@@ -271,7 +284,7 @@ class ResourceProvenance:
             return False
         binding = self.binding(root, node)
         for read in self.reads.get(root, ()):
-            parent = self.context.parents.get(read)
+            parent = self.parents.get(read)
             if isinstance(parent, ast.Attribute | ast.ExceptHandler):
                 continue
             if not self._safe_import_use(read):
@@ -317,7 +330,7 @@ class ResourceProvenance:
         )
 
     def _safe_import_use(self, node: ast.Name | ast.Attribute) -> bool:
-        parent = self.context.parents.get(node)
+        parent = self.parents.get(node)
         return (
             (isinstance(parent, ast.Attribute) and parent.value is node)
             or (isinstance(parent, ast.Call) and parent.func is node)
@@ -337,9 +350,9 @@ class ResourceProvenance:
         binding = self.binding(name.id, at)
         if not isinstance(binding, ast.Name):
             return None
-        statement = self.context.parents.get(binding)
+        statement = self.parents.get(binding)
         if isinstance(statement, ast.withitem):
-            owner = self.context.parents.get(statement)
+            owner = self.parents.get(statement)
             if (
                 binding is statement.optional_vars
                 and self.contains(owner, at)
@@ -351,12 +364,12 @@ class ResourceProvenance:
         return value if isinstance(value, ast.Call) else None
 
     def assignment_value(self, binding: ast.Name, at: ast.AST) -> ast.expr | None:
-        statement = self.context.parents.get(binding)
+        statement = self.parents.get(binding)
         if not isinstance(statement, ast.Assign | ast.AnnAssign):
             return None
         if isinstance(statement, ast.Assign) and len(statement.targets) != 1:
             return None
-        if not isinstance(self.context.parents.get(statement), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+        if not isinstance(self.parents.get(statement), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
             return None
         return statement.value if statement.lineno < getattr(at, "lineno", 0) else None
 
@@ -381,12 +394,10 @@ class ResourceProvenance:
 
     @cached_property
     def dynamic_namespace(self) -> bool:
-        return self.require_static_namespace and dynamic_namespace_access(
-            self.context.nodes(ast.AST), self.context.imports, self.context.parents
-        )
+        return self.require_static_namespace and self.context.dynamic_namespace
 
     def _stable_async_definition(self, function: ast.AsyncFunctionDef) -> ast.AsyncFunctionDef | None:
-        owner = self.context.parents.get(function)
+        owner = self.parents.get(function)
         if not isinstance(owner, ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
             return None
         if function.decorator_list or has_own_yield(function):
@@ -415,10 +426,10 @@ class ResourceProvenance:
         return True
 
     def _function_alias(self, read: ast.Name) -> ast.Name | None:
-        parent = self.context.parents.get(read)
+        parent = self.parents.get(read)
         if not isinstance(parent, ast.Assign | ast.AnnAssign) or parent.value is not read:
             return None
-        if not isinstance(self.context.parents.get(parent), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+        if not isinstance(self.parents.get(parent), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
             return None
         targets = parent.targets if isinstance(parent, ast.Assign) else [parent.target]
         if len(targets) != 1 or not isinstance(targets[0], ast.Name):
@@ -427,7 +438,7 @@ class ResourceProvenance:
         return target if self.binding(target.id, target) is target else None
 
     def _safe_async_read(self, read: ast.Name) -> bool:
-        parent = self.context.parents.get(read)
+        parent = self.parents.get(read)
         if not isinstance(parent, ast.Call):
             return False
         if parent.func is read:
@@ -469,7 +480,7 @@ class ResourceProvenance:
         return self.escape_cache[key]
 
     def _method_or_context_read(self, read: ast.Name, *, allow_context: bool) -> bool:
-        parent = self.context.parents.get(read)
+        parent = self.parents.get(read)
         if allow_context and isinstance(parent, ast.withitem) and parent.context_expr is read:
             return True
         if (
@@ -478,12 +489,12 @@ class ResourceProvenance:
             or parent.attr in {"__setattr__", "__delattr__", "__getattribute__"}
         ):
             return False
-        call = self.context.parents.get(parent)
+        call = self.parents.get(parent)
         return isinstance(call, ast.Call) and call.func is parent
 
     def contains(self, owner: ast.AST | None, node: ast.AST) -> bool:
-        while node in self.context.parents:
-            node = self.context.parents[node]
+        while node in self.parents:
+            node = self.parents[node]
             if node is owner:
                 return True
         return False

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_sql.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import ast
+import re
 from typing import TYPE_CHECKING
 
 from sarj_python_lint.rules._paths import is_test_path
@@ -10,6 +11,15 @@ if TYPE_CHECKING:
     from pathlib import Path
 
 
+_SQL_LINE_END = re.compile(r"[\r\n]")
+_CONTINUED_QUOTE = re.compile(r"[ \t\f\v]*(?:--[^\r\n]*)?[\r\n](?:[ \t\f\v\r\n]|--[^\r\n]*[\r\n])*'")
+POSTGRES_IDENTIFIER_CONTINUATION = r"[A-Za-z0-9_$\u0080-\U0010ffff]"
+POSTGRES_UNQUOTED_IDENTIFIER = rf"[A-Za-z_\u0080-\U0010ffff]{POSTGRES_IDENTIFIER_CONTINUATION}*"
+SQL_WHITESPACE = " \t\r\n\f\v"
+_IDENTIFIER_CONTINUATION = re.compile(POSTGRES_IDENTIFIER_CONTINUATION)
+_DOLLAR_DELIMITER = re.compile(r"\$(?:[A-Za-z_\u0080-\U0010ffff][A-Za-z0-9_\u0080-\U0010ffff]*)?\$")
+
+
 def is_store_module(path: Path) -> bool:
     if is_test_path(path):
         return False
@@ -44,6 +54,7 @@ def strip_sql_noise(
     *,
     mask_dollar_quotes: bool = True,
     mask_double_quotes: bool = True,
+    preserve_quoted_tokens: bool = False,
 ) -> str:
     out = list(text)
     i = 0
@@ -56,8 +67,10 @@ def strip_sql_noise(
             i += 1
             continue
         for offset in range(i, end):
-            if text[offset] != "\n":
+            if text[offset] not in {"\n", "\r"}:
                 out[offset] = " "
+        if preserve_quoted_tokens and text[i] in {"'", '"', "$"}:
+            out[i] = "?"
         i = end
     return "".join(out)
 
@@ -68,7 +81,7 @@ def _quoted_sql_end(text: str, start: int) -> int:
         quote == "'"
         and start > 0
         and text[start - 1] in {"E", "e"}
-        and (start == 1 or not (text[start - 2].isalnum() or text[start - 2] in {"_", "$"}))
+        and (start == 1 or _IDENTIFIER_CONTINUATION.match(text, start - 2) is None)
     )
     i = start + 1
     while i < len(text):
@@ -82,6 +95,9 @@ def _quoted_sql_end(text: str, start: int) -> int:
         if i < len(text) and text[i] == quote:
             i += 1
             continue
+        if escape_string and (continuation := _CONTINUED_QUOTE.match(text, i)) is not None:
+            i = continuation.end()
+            continue
         break
     return i
 
@@ -91,8 +107,8 @@ def _sql_noise_end(text: str, start: int, *, mask_dollar_quotes: bool) -> int |
     if ch in {"'", '"'}:
         return _quoted_sql_end(text, start)
     if text.startswith("--", start) or (ch == "#" and (start == 0 or text[start - 1].isspace())):
-        end = text.find("\n", start)
-        return len(text) if end == -1 else end
+        end = _SQL_LINE_END.search(text, start)
+        return len(text) if end is None else end.start()
     if text.startswith("/*", start):
         return _block_comment_end(text, start)
     if mask_dollar_quotes and ch == "$":
@@ -116,17 +132,11 @@ def _block_comment_end(text: str, start: int) -> int:
 
 
 def _dollar_quote_end(text: str, start: int) -> int | None:
-    if start > 0 and (text[start - 1].isalnum() or text[start - 1] in {"_", "$"}):
+    if start > 0 and _IDENTIFIER_CONTINUATION.match(text, start - 1) is not None:
         return None
-    delimiter_end = text.find("$", start + 1)
-    if delimiter_end == -1:
-        return None
-    tag = text[start + 1 : delimiter_end]
-    valid_tag = not tag or (
-        (tag[0].isalpha() or tag[0] == "_") and all(char.isalnum() or char == "_" for char in tag[1:])
-    )
-    if not valid_tag:
+    match = _DOLLAR_DELIMITER.match(text, start)
+    if match is None:
         return None
-    delimiter = text[start : delimiter_end + 1]
-    close = text.find(delimiter, delimiter_end + 1)
+    delimiter = match[0]
+    close = text.find(delimiter, match.end())
     return None if close == -1 else close + len(delimiter)

{sarj_python_lint-1.64.0 → sarj_python_lint-1.66.1}/src/sarj_python_lint/rules/_store_writes.py

@@ -12,7 +12,6 @@ from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics, sc
 from sarj_python_lint.rules._ast_index import walk
 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
 
 
 if TYPE_CHECKING:
@@ -20,6 +19,7 @@ if TYPE_CHECKING:
 
     from sarj_python_lint._file_context import PythonFileContext
     from sarj_python_lint.rules._imports import ImportIndex
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
 
 
 type Function = ast.FunctionDef | ast.AsyncFunctionDef
@@ -187,7 +187,7 @@ def _comprehension_scopes(
 class StoreOwners:
     def __init__(self, context: PythonFileContext) -> None:
         self.context = context
-        self.provenance = ResourceProvenance(context, require_static_namespace=True)
+        self.provenance = context.static_resource_provenance
         self.project = context.session.project
 
     def receiver(self, expression: ast.expr, at: ast.AST) -> tuple[ast.ClassDef, ImportIndex] | None:
@@ -290,7 +290,7 @@ class StoreOwners:
         from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- defer to avoid the rule registry's context import cycle.
 
         definition = PythonFileContext(owner.path, owner.source, self.context.session)
-        provenance = ResourceProvenance(definition, require_static_namespace=True)
+        provenance = definition.static_resource_provenance
         if (
             provenance.dynamic_namespace
             or provenance.wildcard