sarj-python-lint 1.101.0__tar.gz → 1.101.10__tar.gz

{sarj_python_lint-1.101.0 → sarj_python_lint-1.101.10}/PKG-INFO

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

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

{sarj_python_lint-1.101.0 → sarj_python_lint-1.101.10}/src/sarj_python_lint/rules/_opaque_contracts.py

@@ -16,6 +16,7 @@ if TYPE_CHECKING:
     from pathlib import Path
 
     from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._local_source import LocalSourceFacts
 
 
 type _Function = ast.FunctionDef | ast.AsyncFunctionDef
@@ -111,11 +112,13 @@ class OpaqueContractFacts:
         context: PythonFileContext,
         facts: MappingShapeFacts,
         *,
+        local_source: LocalSourceFacts,
         modules: dict[Path, OpaqueContractFacts] | None = None,
         budget: _ProofBudget | None = None,
     ) -> None:
         self.context = context
         self.facts = facts
+        self.local_source = local_source
         self.native = NativeObjectContracts(context, facts)
         self.guards: dict[str, _Refinement | None] = {}
         self.checked: dict[_Function, frozenset[ast.arg]] = {}
@@ -712,20 +715,24 @@ class OpaqueContractFacts:
 
     def _imported_source(self, qualified: str) -> tuple[OpaqueContractFacts, ast.FunctionDef] | None:
         module, _, name = qualified.rpartition(".")
-        path = self.context.session.local_source.resolve_module(
-            self.context.path, module, 0, facts=self.context.session.first_party
-        )
+        path = self.local_source.resolve_module(self.context.path, module, 0, facts=self.context.session.first_party)
         if path is not None and (owner := self.modules.get(path.resolve())) is not None:
             return owner.export(name)
         if len(self.modules) >= _MAX_GUARDS:
             return None
-        loaded = self.context.session.local_source.read_module(path) if path is not None else None
+        loaded = self.local_source.read_module(path) if path is not None else None
         if loaded is None:
             return None
         from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- source loading runs after AnalysisSession initialization.
 
         context = PythonFileContext(loaded.path, loaded.source, self.context.session)
-        owner = OpaqueContractFacts(context, MappingShapeFacts(context), modules=self.modules, budget=self.budget)
+        owner = OpaqueContractFacts(
+            context,
+            MappingShapeFacts(context),
+            local_source=self.local_source,
+            modules=self.modules,
+            budget=self.budget,
+        )
         return owner.export(name)
 
     def export(self, name: str) -> tuple[OpaqueContractFacts, ast.FunctionDef] | None:

sarj_python_lint-1.101.10/src/sarj_python_lint/rules/_postgres_ctas.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+import sqlglot
+from sqlglot import exp
+from sqlglot.errors import SqlglotError
+from sqlglot.tokenizer_core import TokenType
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sqlglot.tokenizer_core import Token
+
+
+_COPY_END = re.compile(r"(?m)^\\\.(?:\r?$)")
+_TEMP_TABLE = (TokenType.CREATE, TokenType.TEMPORARY, TokenType.TABLE)
+_ON_COMMIT_DROP = (TokenType.ON, TokenType.COMMIT, TokenType.DROP)
+_ON_COMMIT_ROWS_SIZE = 4
+
+
+def normalize_postgres_ctas(source: str) -> str:
+    source = _mask_copy_input(source)
+    try:
+        tokens = sqlglot.tokenize(source, read="postgres")
+    except SqlglotError, RecursionError:
+        return source
+    output = list(source)
+    statement: list[Token] = []
+    for token in tokens:
+        if token.token_type is not TokenType.SEMICOLON:
+            statement.append(token)
+            continue
+        _normalize_header(output, statement)
+        statement = []
+    _normalize_header(output, statement)
+    return "".join(output)
+
+
+def _mask_copy_input(source: str) -> str:
+    if "COPY" not in source.upper():
+        return source
+    output = list(source)
+    start = 0
+    for separator in re.finditer(r";", source):
+        if separator.start() < start:
+            continue
+        try:
+            tokens = sqlglot.tokenize(source[start : separator.end()], read="postgres")
+        except SqlglotError, RecursionError:
+            continue
+        if not tokens or tokens[-1].token_type is not TokenType.SEMICOLON:
+            continue
+        if start + tokens[-1].end != separator.start():
+            continue
+        if _copy_from_stdin(tokens):
+            marker = _COPY_END.search(source, separator.end())
+            end = marker.end() if marker is not None else len(source)
+            _blank(output, start, end)
+            start = end
+        else:
+            start = separator.end()
+    return "".join(output)
+
+
+def _normalize_header(output: list[str], tokens: Sequence[Token]) -> None:
+    if not _is_table_create(tokens):
+        return
+    depth = 0
+    for index, token in enumerate(tokens):
+        if token.token_type is TokenType.L_PAREN:
+            depth += 1
+        elif token.token_type is TokenType.R_PAREN:
+            depth -= 1
+        elif depth == 0 and token.token_type is TokenType.ALIAS:
+            spans = _ignored_header_spans(tokens[:index])
+            if not spans:
+                return
+            start = tokens[0].start
+            candidate = output[start : tokens[-1].end + 1]
+            for first, last in spans:
+                _blank(candidate, first.start - start, last.end + 1 - start)
+            if _is_query_create("".join(candidate)):
+                for first, last in spans:
+                    _blank(output, first.start, last.end + 1)
+            return
+
+
+def _temporary_qualifier(tokens: Sequence[Token]) -> Token | None:
+    if len(tokens) > 1 and tokens[1].token_type is TokenType.VAR and tokens[1].text.upper() in {"GLOBAL", "LOCAL"}:
+        return tokens[1]
+    return None
+
+
+def _is_table_create(tokens: Sequence[Token]) -> bool:
+    kinds = tuple(token.token_type for token in tokens[:4])
+    if kinds[:2] == (TokenType.CREATE, TokenType.TABLE) or kinds[:3] == _TEMP_TABLE:
+        return True
+    if kinds[:3] == (TokenType.CREATE, TokenType.VAR, TokenType.TABLE):
+        return tokens[1].text.upper() == "UNLOGGED"
+    return (
+        kinds == (TokenType.CREATE, TokenType.VAR, TokenType.TEMPORARY, TokenType.TABLE)
+        and _temporary_qualifier(tokens) is not None
+    )
+
+
+def _ignored_header_spans(tokens: Sequence[Token]) -> tuple[tuple[Token, Token], ...]:
+    spans: list[tuple[Token, Token]] = []
+    qualifier = _temporary_qualifier(tokens)
+    if qualifier is not None:
+        spans.append((qualifier, qualifier))
+    end = len(tokens)
+    if _has_tablespace_property(tokens):
+        spans.append((tokens[-2], tokens[-1]))
+        end -= 2
+    commit_start = _commit_property_start(tokens, end)
+    if commit_start < end and tokens[end - 1].token_type is TokenType.DROP:
+        spans.append((tokens[commit_start], tokens[end - 1]))
+    if _has_without_oids_property(tokens[:commit_start]):
+        spans.append((tokens[commit_start - 2], tokens[commit_start - 1]))
+    return tuple(spans)
+
+
+def _commit_property_start(tokens: Sequence[Token], end: int) -> int:
+    if tuple(token.token_type for token in tokens[end - 3 : end]) == _ON_COMMIT_DROP:
+        return end - 3
+    if end < _ON_COMMIT_ROWS_SIZE or tuple(
+        token.token_type for token in tokens[end - _ON_COMMIT_ROWS_SIZE : end - 2]
+    ) != (TokenType.ON, TokenType.COMMIT):
+        return end
+    action, rows = tokens[end - 2 : end]
+    if rows.token_type is TokenType.ROWS and (
+        action.token_type is TokenType.DELETE
+        or (action.token_type is TokenType.VAR and action.text.upper() == "PRESERVE")
+    ):
+        return end - _ON_COMMIT_ROWS_SIZE
+    return end
+
+
+def _has_without_oids_property(tokens: Sequence[Token]) -> bool:
+    return (
+        len(tokens) > 1
+        and tokens[-2].token_type is TokenType.VAR
+        and tokens[-1].token_type is TokenType.VAR
+        and tokens[-2].text.upper() == "WITHOUT"
+        and tokens[-1].text.upper() == "OIDS"
+    )
+
+
+def _has_tablespace_property(tokens: Sequence[Token]) -> bool:
+    return (
+        len(tokens) > 1
+        and tokens[-2].token_type is TokenType.VAR
+        and tokens[-2].text.upper() == "TABLESPACE"
+        and tokens[-1].token_type in {TokenType.VAR, TokenType.IDENTIFIER}
+    )
+
+
+def _is_query_create(candidate: str) -> bool:
+    try:
+        parsed = sqlglot.parse_one(candidate, read="postgres")
+    except SqlglotError, RecursionError:
+        return False
+    return (
+        isinstance(parsed, exp.Create)
+        and parsed.args.get("kind") == "TABLE"
+        and isinstance(parsed.args.get("expression"), exp.Query)
+    )
+
+
+def _copy_from_stdin(tokens: Sequence[Token]) -> bool:
+    if not tokens or tokens[0].token_type is not TokenType.COPY:
+        return False
+    depth = 0
+    for index, token in enumerate(tokens[:-1]):
+        if token.token_type is TokenType.L_PAREN:
+            depth += 1
+        elif token.token_type is TokenType.R_PAREN:
+            depth -= 1
+        elif depth == 0 and token.token_type is TokenType.FROM:
+            following = tokens[index + 1]
+            return following.token_type is TokenType.VAR and following.text.upper() == "STDIN"
+    return False
+
+
+def _blank(output: list[str], start: int, end: int) -> None:
+    for index in range(start, end):
+        if output[index] not in {"\r", "\n"}:
+            output[index] = " "

{sarj_python_lint-1.101.0 → sarj_python_lint-1.101.10}/src/sarj_python_lint/rules/_transactional_sql.py

@@ -87,6 +87,7 @@ _NATIVE_CONNECTIONS = frozenset(
 )
 _SELECT = re.compile(r"\bSELECT\b", re.IGNORECASE)
 _PLACEHOLDER = re.compile(r"%(?:\([^)]+\))?s")
+_POSTGRES_PLACEHOLDER = re.compile(r"%%|%(?:\([^)]+\))?[sbt]")
 _FORMAT_HOLE = re.compile(r"(?<!\{)\{(?:[A-Za-z_]\w*|\d*)\}(?!\})")
 _SQL_HOLE = "__sarj_sql_hole__"
 _MAX_WRAPPER_DEPTH = 8
@@ -127,11 +128,19 @@ def query_signal(sql: str, *, dialect: str = "postgres") -> str | None:
 
 
 def _prepared_sql(sql: str, dialect: str) -> str:
-    prepared = _FORMAT_HOLE.sub(_SQL_HOLE, _PLACEHOLDER.sub("?", sql))
-    if dialect == "postgres" and "EXPLAIN" in prepared.upper():
-        from sarj_python_lint.rules._sql_explain import normalize_postgres_explain  # ruff: ignore[import-outside-top-level] -- only executing EXPLAIN needs native token normalization.
+    parameters = _POSTGRES_PLACEHOLDER if dialect == "postgres" else _PLACEHOLDER
+    prepared = _FORMAT_HOLE.sub(
+        _SQL_HOLE,
+        parameters.sub(lambda match: ("%" if match.group() == "%%" else "?").ljust(len(match.group())), sql),
+    )
+    if dialect == "postgres":
+        from sarj_python_lint.rules._postgres_ctas import normalize_postgres_ctas  # ruff: ignore[import-outside-top-level] -- recover PostgreSQL temporary-table queries only after the SELECT gate.
+
+        prepared = normalize_postgres_ctas(prepared)
+        if "EXPLAIN" in prepared.upper():
+            from sarj_python_lint.rules._sql_explain import normalize_postgres_explain  # ruff: ignore[import-outside-top-level] -- only executing EXPLAIN needs native token normalization.
 
-        prepared = normalize_postgres_explain(prepared)
+            prepared = normalize_postgres_ctas(normalize_postgres_explain(prepared))
     if "GROUP" in prepared.upper() and ("/*" in prepared or "--" in prepared):
         import sqlglot  # ruff: ignore[import-outside-top-level] -- tokenize only GROUP candidates with comments.
 
@@ -173,13 +182,14 @@ def _statement_signal(statement: exp.Expr, sql: str, dialect: str) -> str | None
 
 
 def transactional_queries(context: PythonFileContext) -> Iterator[TransactionalQuery]:
-    if _SELECT.search(context.source) is None:
+    queries = tuple(_recover_queries(context))
+    if not queries:
         return
     dialects = _source_dialects(context)
     if not dialects or dialects == {"analytical"}:
         return
     single = next(iter(dialects)) if len(dialects) == 1 else None
-    for candidate in _recover_queries(context):
+    for candidate in queries:
         dialect = single or _executing_dialect(candidate.node, context)
         if dialect is not None and dialect != "analytical":
             yield TransactionalQuery(candidate.node, candidate.sql, dialect)

{sarj_python_lint-1.101.0 → sarj_python_lint-1.101.10}/src/sarj_python_lint/rules/no_analytical_aggregation_in_postgres_store.py

@@ -34,7 +34,7 @@ _COMMON_AGGREGATE = re.compile(
     re.IGNORECASE,
 )
 _LOCKING_READ = re.compile(r"\b(?:FOR\s+(?:NO\s+KEY\s+)?UPDATE|FOR\s+SHARE|SKIP\s+LOCKED)\b", re.IGNORECASE)
-_PLACEHOLDER = re.compile(r"%(?:\([^)]+\))?s")
+_PLACEHOLDER = re.compile(r"%%|%(?:\([^)]+\))?[sbt]")
 _GROUP_KEYS_LIMIT = 2
 _GROUP_AGGREGATES_LIMIT = 2
 _SINGLE_GROUP_AGGREGATES_LIMIT = 3
@@ -68,7 +68,9 @@ def _grouped_reporting_signal(sql: str) -> str | None:
     if _GROUP_BY.search(sql) is None or _COMMON_AGGREGATE.search(sql) is None:
         return None
     try:
-        statements = parse_postgres(_PLACEHOLDER.sub("?", sql))
+        statements = parse_postgres(
+            _PLACEHOLDER.sub(lambda match: ("%" if match.group() == "%%" else "?").ljust(len(match.group())), sql)
+        )
     except SqlglotError, RecursionError:
         return None
     for statement in statements:
@@ -141,7 +143,7 @@ class NoAnalyticalAggregationInPostgresStore(Rule):
         aliases=("no-aggregation-in-store-query", "no-analytical-queries-in-transactional-db"),
         limitations=(
             "Statically recoverable SQL in non-test, non-generated Python modules with native PostgreSQL, MySQL, or SQLite imports is analyzed, regardless of filename. The historical SARJ020 identifier is retained.",
-            "Every parsed SELECT DISTINCT (including DISTINCT ON), deduplicating UNION/INTERSECT/EXCEPT, GROUP BY, and built-in SQL aggregate is reported, including CTEs, nested writes, windowed aggregates, identity-bounded queries, and LIMIT queries. ALL set operations remain valid. This deliberately replaces the former reporting-size thresholds.",
+            "Every parsed SELECT DISTINCT (including DISTINCT ON), deduplicating UNION/INTERSECT/EXCEPT, GROUP BY, and built-in SQL aggregate is reported, including temporary-table AS queries, CTEs, nested writes, windowed aggregates, identity-bounded queries, and LIMIT queries. ALL set operations remain valid. This deliberately replaces the former reporting-size thresholds.",
             "A single imported backend owns module SQL. Resolvable first-party query contracts and re-exports retain their native analytical-provider evidence. Mixed backend modules require a direct query sink on a source-proven native connection or annotated parameter; unresolved receivers and separately bound queries abstain.",
             "Known ClickHouse, BigQuery, DuckDB, Snowflake, Trino, Athena, and Databricks drivers are analytical owners. Comments, scalar SQL values, identifiers, Python docstrings, and IS DISTINCT FROM do not trigger the policy.",
             "SQLite multi-argument MIN/MAX and MySQL ANY_VALUE retain their scalar semantics; PostgreSQL ANY_VALUE remains an aggregate.",
@@ -165,6 +167,40 @@ class NoAnalyticalAggregationInPostgresStore(Rule):
                 expected_count=1,
                 public=True,
             ),
+            RuleExample(
+                example_id="temporary-table-distinct",
+                scenario="temporary-table",
+                title="A temporary PostgreSQL table still performs deduplication",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/event_store.py",
+                        "import psycopg\n\n"
+                        'QUERY = "CREATE TEMP TABLE report ON COMMIT DROP AS WITH rows AS '
+                        '(SELECT DISTINCT team_id FROM event) SELECT team_id FROM rows"\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/event_store.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="temporary-table-operational-read",
+                scenario="temporary-table",
+                title="A temporary PostgreSQL table can materialize an operational row lookup",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/event_store.py",
+                        "import psycopg\n\n"
+                        'QUERY = "CREATE TEMP TABLE report ON COMMIT DROP AS WITH rows AS '
+                        '(SELECT team_id FROM event WHERE id = %s) SELECT team_id FROM rows"\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/event_store.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="operational-existence-lookup",
                 title="PostgreSQL performs an operational existence lookup",

{sarj_python_lint-1.101.0 → sarj_python_lint-1.101.10}/src/sarj_python_lint/rules/prefer_precise_object_contract.py

@@ -15,6 +15,7 @@ from sarj_python_lint.rule_base import (
     RuleExample,
     Severity,
 )
+from sarj_python_lint.rules._local_source import LocalSourceFacts
 from sarj_python_lint.rules._native_object_contracts import builtin_object, builtin_symbol
 from sarj_python_lint.rules._opaque_contracts import REFINEMENT_TYPES, OpaqueContractFacts
 from sarj_python_lint.rules.require_pydantic_for_mapping_shape import MappingShapeFacts
@@ -48,7 +49,7 @@ class PreferPreciseObjectContract(Rule):
             "Safe fixes narrow only a bare builtin object return annotation to builtin str for a closed private nested synchronous helper returning one exact string literal, with every call used directly as an if test and all containing return contracts explicit. Existing inert/metadata/binding proofs must hold; public/domain/container/parameter/model contracts and other result uses remain review-only.",
             "Checks builtin object in function signatures and class field annotations, including supported containers, callables, optional unions and quoted annotations. Local opaque values, object() sentinels, Literal/Annotated metadata, framework hooks, proven override signatures, and registered raw Pydantic callbacks are excluded. Functions that directly validate an object parameter through a source-visible BaseModel, BaseSettings or RootModel model_validate call, positionally or with obj=, retain that raw boundary. JSON text inputs still require a text or byte contract. Aliases must resolve to their source declaration and their bodies use definition scope. Alias graphs are bounded and shared branches reuse their facts. Imported or shadowed application types named object are preserved. Genuine opaque public contracts can use an explained exact-code exception; narrowing outside the exact private truthiness-only subset remains manual.",
             "An import-proven TypeGuard or TypeIs retains bare object on its guarded positional parameter and unchecked object slots in its declared refinement result; other object parameters remain checked. Guard correctness belongs to the type-guard rules. Universal type[object] class contracts and the return of a canonical module-level PEP 562 __getattr__ hook retain their opaque runtime contracts.",
-            "Ordinary raw validators retain object inputs tied to builtin isinstance, exact builtin type comparisons or an actual source-resolved TypeGuard/TypeIs through rejecting branches, actual type/refinement assertions, accepting terminal branches with a rejecting fallback, or conditional expressions. Stable projections from containers with unchecked value slots retain their raw root contract when those values are validated. Source-visible local and imported validators may delegate those inputs and raw results; precise result narrowing does not justify a bare object output. Related unchecked mapping projections and transforms retain unknown values; import-proven native parsers and JSONDecoder preserve raw outputs. Universal builtin and stdlib interoperation may retain raw inputs. Independent object parameters, domain constructors and unproven parser names remain checked. Source resolution and dataflow are bounded with cycle guards; rebinding, decorators and namespace mutation invalidate delegated proof.",
+            "Ordinary raw validators retain object inputs tied to builtin isinstance, exact builtin type comparisons or an actual source-resolved TypeGuard/TypeIs through rejecting branches, actual type/refinement assertions, accepting terminal branches with a rejecting fallback, or conditional expressions. Stable projections from containers with unchecked value slots retain their raw root contract when those values are validated. Source-visible local and imported validators may delegate those inputs and raw results; precise result narrowing does not justify a bare object output. Related unchecked mapping projections and transforms retain unknown values; import-proven native parsers and JSONDecoder preserve raw outputs. Universal builtin and stdlib interoperation may retain raw inputs. Independent object parameters, domain constructors and unproven parser names remain checked. Source resolution and dataflow use a bounded per-file proof cache, captured source inputs and cycle guards; rebinding, decorators and namespace mutation invalidate delegated proof.",
             "Native opaque contracts include canonical ast.Constant.value reads and captures, FunctionType invocations, identity-only inputs and sys.getrefcount. Actual exec/eval globals and locals retain unknown values only through bounded native dict construction and alias flow; unrelated dictionaries and source domain factories do not borrow that ownership. Stub property returns on an import-proven runtime_checkable Protocol retain unchecked incoming attributes. Generic callable results, ordinary Protocol methods, application properties and unused parameters remain checked.",
             "Raw input unions may include scalar or None branches; only genuine unchecked container branches seed raw projections. Mapping consumers that inspect only keys retain uninspected value slots. Projected aliases require simple statement dominance, and precise active guards permit typed consumption after validation. Native namespace output reads require a preceding direct function-scope execution and abstain after authored mutations. Benign builtins imports do not hide builtin object contracts; explicit object shadowing and source-visible object mutations remain outside scope.",
             "An import-proven Iterable of unchecked values retains its raw element contract when every input use is a direct synchronous iteration and every reachable element read directly enters source-proven Pydantic model_validate. Deferred closures, rebinding, other iterator/element uses, unknown model providers and JSON-text parsers do not establish that boundary.",
@@ -131,7 +132,9 @@ class PreferPreciseObjectContract(Rule):
         if facts.provenance.wildcard:
             return []
         findings: list[Diagnostic] = []
-        opaque = OpaqueContractFacts(context, facts)
+        opaque = OpaqueContractFacts(
+            context, facts, local_source=LocalSourceFacts(source_inputs=context.session.source_inputs)
+        )
         for owner, annotation in _contracts(context):
             if not _has_object(annotation, context, facts, at=annotation):
                 continue