sarj-python-lint 1.84.0__tar.gz → 1.85.0__tar.gz

{sarj_python_lint-1.84.0 → sarj_python_lint-1.85.0}/PKG-INFO

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

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

{sarj_python_lint-1.84.0 → sarj_python_lint-1.85.0}/src/sarj_python_lint/_autofix.py

@@ -759,6 +759,8 @@ def _primitive_set(node: ast.expr) -> bool:
 
 
 def _dispatch_fix(source: _Source, diagnostic: Diagnostic) -> list[TextEdit]:
+    if diagnostic.code == "SARJ080" and diagnostic.severity is not Severity.ERROR:
+        return []
     for root in source.context.nodes(ast.If):
         if not _at(root, diagnostic) or source.comments_between(root.lineno, _last_line(root)):
             continue

{sarj_python_lint-1.84.0 → sarj_python_lint-1.85.0}/src/sarj_python_lint/_file_context.py

@@ -22,6 +22,7 @@ if TYPE_CHECKING:
 
     from sarj_python_lint.rules._copy_on_write import CopyOnWriteAnalysis
     from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+    from sarj_python_lint.rules._store_sql import StoreQuery
     from sarj_python_lint.rules._test_provenance import TestProvenance
 
 
@@ -31,6 +32,7 @@ class PythonFileContext:
         self.path = path
         self.source = source
         self.session = session if session is not None else AnalysisSession()
+        self.store_queries: tuple[StoreQuery, ...] | None = None
 
     @cached_property
     def symbol_source(self) -> str:

sarj_python_lint-1.85.0/src/sarj_python_lint/rules/_postgres.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import override
+
+from sqlglot import exp, parse
+from sqlglot.dialects.postgres import Postgres
+
+
+def parse_postgres(source: str) -> list[exp.Expr | None]:
+    return parse(source, read=_PostgresForLint)
+
+
+class _PostgresForLint(Postgres):
+    class Parser(Postgres.Parser):
+        @override
+        def _warn_unsupported(self) -> None:
+            """Unsupported input must not copy private SQL into dependency logs."""

{sarj_python_lint-1.84.0 → sarj_python_lint-1.85.0}/src/sarj_python_lint/rules/_registry.py

@@ -228,7 +228,9 @@ from sarj_python_lint.rules.nan_hidden_by_builtin_min import NanHiddenByBuiltinM
 from sarj_python_lint.rules.no_conflicting_pydantic_alias_validation import NoConflictingPydanticAliasValidation
 from sarj_python_lint.rules.no_contradictory_type_guard import NoContradictoryTypeGuard
 from sarj_python_lint.rules.no_create_verb_in_post_path import NoCreateVerbInPostPath
+from sarj_python_lint.rules.no_custom_control_flow_exception import NoCustomControlFlowException
 from sarj_python_lint.rules.no_defaulted_environment_setting import NoDefaultedEnvironmentSetting
+from sarj_python_lint.rules.no_discarded_tagged_outcome import NoDiscardedTaggedOutcome
 from sarj_python_lint.rules.no_duplicate_field_validator_body import NoDuplicateFieldValidatorBody
 from sarj_python_lint.rules.no_exception_text_in_500_detail import NoExceptionTextIn500Detail
 from sarj_python_lint.rules.no_folded_bad_request_not_found import NoFoldedBadRequestNotFound
@@ -237,15 +239,19 @@ from sarj_python_lint.rules.no_impossible_pydantic_field_bounds import NoImpossi
 from sarj_python_lint.rules.no_invalid_pydantic_bypass import NoInvalidPydanticBypass
 from sarj_python_lint.rules.no_invalid_pydantic_validator_return import NoInvalidPydanticValidatorReturn
 from sarj_python_lint.rules.no_partial_type_is import NoPartialTypeIs
+from sarj_python_lint.rules.no_recording_store import NoRecordingStore
 from sarj_python_lint.rules.no_redundant_local_alias import NoRedundantLocalAlias
+from sarj_python_lint.rules.no_redundant_sql_alias import NoRedundantSqlAlias
 from sarj_python_lint.rules.no_shallow_record_type_guard import NoShallowRecordTypeGuard
 from sarj_python_lint.rules.no_slash_collection_root_under_prefix import NoSlashCollectionRootUnderPrefix
 from sarj_python_lint.rules.no_unknown_pydantic_validator_field import NoUnknownPydanticValidatorField
 from sarj_python_lint.rules.no_work_verb_get_route import NoWorkVerbGetRoute
+from sarj_python_lint.rules.prefer_application_model_joins import PreferApplicationModelJoins
 from sarj_python_lint.rules.prefer_bulk_upsert import PreferBulkUpsert
 from sarj_python_lint.rules.prefer_direct_import_module import PreferDirectImportModule
 from sarj_python_lint.rules.prefer_discriminated_model_union import PreferDiscriminatedModelUnion
 from sarj_python_lint.rules.prefer_grouped_settings import PreferGroupedSettings
+from sarj_python_lint.rules.prefer_optional_composite import PreferOptionalComposite
 from sarj_python_lint.rules.prefer_precise_object_contract import PreferPreciseObjectContract
 from sarj_python_lint.rules.prefer_psycopg_executemany import PreferPsycopgExecutemany
 from sarj_python_lint.rules.prefer_pydantic_model_assertion import PreferPydanticModelAssertion
@@ -259,11 +265,23 @@ from sarj_python_lint.rules.redundant_test_constructor_forwarder import Redundan
 from sarj_python_lint.rules.repeated_unimplemented_test_contract import RepeatedUnimplementedTestContract
 from sarj_python_lint.rules.require_exp_on_jwt_decode import RequireExpOnJwtDecode
 from sarj_python_lint.rules.store_field_update_reuses_upsert import StoreFieldUpdateReusesUpsert
+from sarj_python_lint.rules.store_insert_requires_explicit_conflict_policy import (
+    StoreInsertRequiresExplicitConflictPolicy,
+)
+from sarj_python_lint.rules.store_mutation_command_fanout import StoreMutationCommandFanout
 from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOracle
 
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        NoDiscardedTaggedOutcome.id: NoDiscardedTaggedOutcome,
+        StoreInsertRequiresExplicitConflictPolicy.id: StoreInsertRequiresExplicitConflictPolicy,
+        StoreMutationCommandFanout.id: StoreMutationCommandFanout,
+        PreferApplicationModelJoins.id: PreferApplicationModelJoins,
+        NoRecordingStore.id: NoRecordingStore,
+        NoRedundantSqlAlias.id: NoRedundantSqlAlias,
+        NoCustomControlFlowException.id: NoCustomControlFlowException,
+        PreferOptionalComposite.id: PreferOptionalComposite,
         AsyncSubprocessCancellationCleanup.id: AsyncSubprocessCancellationCleanup,
         CancelOwnedTaskWithoutJoin.id: CancelOwnedTaskWithoutJoin,
         AsyncExecutorShutdown.id: AsyncExecutorShutdown,

sarj_python_lint-1.85.0/src/sarj_python_lint/rules/_store_sql.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+import re
+from typing import TYPE_CHECKING
+
+from sqlglot import exp
+
+from sarj_python_lint.rules._sql import sql_string_value
+from sarj_python_lint.rules._store_writes import Function, methods
+from sarj_python_lint.rules.no_psycopg_execution_outside_injected_owner import psycopg_execution_calls
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_HOLE = "__sarj_store_sql_hole__"
+_FORMAT_HOLE = re.compile(r"(?<!\{)\{(?:[A-Za-z_]\w*|\d*)\}(?!\})")
+_MAX_RECOVERY_DEPTH = 8
+
+
+@dataclass(frozen=True)
+class StoreQuery:
+    node: ast.expr
+    owner: ast.ClassDef | None
+    method: Function | None
+    sql: str
+    statement: exp.Expr
+
+
+@dataclass(frozen=True)
+class QueryOwner:
+    owner: ast.ClassDef | None
+    method: Function | None
+
+
+@dataclass(frozen=True)
+class _MethodWrites:
+    qualified: frozenset[tuple[str, str]]
+    instances: frozenset[tuple[ast.ClassDef, str]]
+
+
+def store_queries(context: PythonFileContext) -> Iterator[StoreQuery]:
+    if context.store_queries is None:
+        context.store_queries = tuple(recover_store_queries(context))
+    return iter(context.store_queries)
+
+
+def recover_store_queries(context: PythonFileContext) -> Iterator[StoreQuery]:
+    calls = psycopg_execution_calls(context, include_injected=True, include_probes=False)
+    wrappers = _query_wrappers(calls, context)
+    for call in calls:
+        argument = _execution_argument(call)
+        if argument is not None:
+            yield from _parsed_query(argument, call, context)
+    for call in context.nodes(ast.Call):
+        yield from _forwarded_query(call, wrappers, context)
+
+
+def _forwarded_query(
+    call: ast.Call, wrappers: dict[tuple[ast.ClassDef, str], tuple[int, str]], context: PythonFileContext
+) -> Iterator[StoreQuery]:
+    if (
+        not isinstance(call.func, ast.Attribute)
+        or not isinstance(call.func.value, ast.Name)
+        or call.func.value.id != "self"
+    ):
+        return
+    scope = query_owner(call, context)
+    wrapper = wrappers.get((scope.owner, call.func.attr)) if scope.owner is not None else None
+    if wrapper is None:
+        return
+    positional, parameter = wrapper
+    expression = (
+        call.args[positional]
+        if positional < len(call.args)
+        else next((keyword.value for keyword in call.keywords if keyword.arg == parameter), None)
+    )
+    if expression is not None:
+        yield from _parsed_query(expression, call, context)
+
+
+def _execution_argument(call: ast.Call) -> ast.expr | None:
+    return call.args[0] if call.args else next((item.value for item in call.keywords if item.arg == "query"), None)
+
+
+def _query_wrappers(
+    calls: list[ast.Call], context: PythonFileContext
+) -> dict[tuple[ast.ClassDef, str], tuple[int, str]]:
+    wrappers: dict[tuple[ast.ClassDef, str], tuple[int, str]] = {}
+    if not calls:
+        return wrappers
+    writes = _method_writes(context)
+    owner_methods: dict[ast.ClassDef, dict[str, Function]] = {}
+    for call in calls:
+        scope = query_owner(call, context)
+        owner, method = scope.owner, scope.method
+        argument = _execution_argument(call)
+        if owner is None or method is None or not isinstance(argument, ast.Name):
+            continue
+        if owner not in owner_methods:
+            owner_methods[owner] = methods(owner)
+        if (
+            owner_methods[owner].get(method.name) is not method
+            or (owner.name, method.name) in writes.qualified
+            or (owner, method.name) in writes.instances
+        ):
+            continue
+        parameters = [*method.args.posonlyargs, *method.args.args]
+        if not parameters or parameters[0].arg != "self":
+            continue
+        positions = {value.arg: index for index, value in enumerate(parameters[1:])}
+        position = positions.get(argument.id)
+        binding = context.static_resource_provenance.runtime_binding(argument.id, argument)
+        if position is not None and binding is parameters[position + 1]:
+            wrappers[owner, method.name] = (position, argument.id)
+    return wrappers
+
+
+def _method_writes(context: PythonFileContext) -> _MethodWrites:
+    qualified: set[tuple[str, str]] = set()
+    instances: set[tuple[ast.ClassDef, str]] = set()
+    for node in context.nodes(ast.Attribute):
+        if not isinstance(node.ctx, ast.Store | ast.Del) or not isinstance(node.value, ast.Name):
+            continue
+        qualified.add((node.value.id, node.attr))
+        if node.value.id == "self":
+            owner = query_owner(node, context).owner
+            if owner is not None:
+                instances.add((owner, node.attr))
+    return _MethodWrites(frozenset(qualified), frozenset(instances))
+
+
+def query_owner(node: ast.AST, context: PythonFileContext) -> QueryOwner:
+    current = context.parents.get(node)
+    while current is not None and not isinstance(current, ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda):
+        current = context.parents.get(current)
+    if not isinstance(current, ast.FunctionDef | ast.AsyncFunctionDef):
+        return QueryOwner(None, None)
+    parent = context.parents.get(current)
+    return QueryOwner(parent if isinstance(parent, ast.ClassDef) else None, current)
+
+
+def _parsed_query(expression: ast.expr, call: ast.Call, context: PythonFileContext) -> Iterator[StoreQuery]:
+    text = _query_text(expression, context, seen=frozenset())
+    if text is None:
+        return
+    from sqlglot.errors import SqlglotError  # ruff: ignore[import-outside-top-level] -- malformed input abstains.
+
+    from sarj_python_lint.rules._postgres import parse_postgres  # ruff: ignore[import-outside-top-level] -- avoid private-source unsupported SQL logs.
+
+    try:
+        statements = parse_postgres(_FORMAT_HOLE.sub(_HOLE, text))
+    except SqlglotError, RecursionError:
+        return
+    scope = query_owner(call, context)
+    for statement in statements:
+        if statement is not None:
+            yield StoreQuery(_query_origin(expression, context), scope.owner, scope.method, text, statement)
+
+
+def _query_origin(expression: ast.expr, context: PythonFileContext) -> ast.expr:
+    seen: set[int] = set()
+    while id(expression) not in seen and len(seen) < _MAX_RECOVERY_DEPTH:
+        seen.add(id(expression))
+        if isinstance(expression, ast.Name):
+            value = _bound_value(expression, context)
+            if value is not None:
+                expression = value
+                continue
+        if (
+            isinstance(expression, ast.Call)
+            and isinstance(expression.func, ast.Attribute)
+            and expression.func.attr == "format"
+        ):
+            expression = expression.func.value
+            continue
+        if (
+            isinstance(expression, ast.Call)
+            and expression.args
+            and context.static_resource_provenance.runtime_import_name(expression.func) == "psycopg.sql.SQL"
+        ):
+            expression = expression.args[0]
+            continue
+        break
+    return expression
+
+
+def relation_key(node: exp.Expr | None) -> tuple[str, ...] | None:
+    from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- native table identity for parsed queries.
+
+    if not isinstance(node, exp.Table) or not isinstance(sql_child(node, "this"), exp.Identifier):
+        return None
+    parts = (sql_child(node, "catalog"), sql_child(node, "db"), sql_child(node, "this"))
+    identifiers = [part for part in parts if part is not None]
+    if not all(isinstance(part, exp.Identifier) for part in identifiers):
+        return None
+    if any(not part.args.get("quoted") and not part.name.isascii() for part in identifiers):
+        return None
+    names = tuple(part.name if part.args.get("quoted") else part.name.lower() for part in identifiers)
+    return None if any(_HOLE in name for name in names) else names
+
+
+def sql_child(node: exp.Expr, key: str) -> exp.Expr | None:
+    return next((child for child in node.iter_expressions() if child.arg_key == key), None)
+
+
+def sql_children(node: exp.Expr, key: str) -> tuple[exp.Expr, ...]:
+    return tuple(child for child in node.iter_expressions() if child.arg_key == key)
+
+
+def _query_text(expression: ast.expr, context: PythonFileContext, *, seen: frozenset[int]) -> str | None:
+    if id(expression) in seen or len(seen) >= _MAX_RECOVERY_DEPTH:
+        return None
+    seen |= {id(expression)}
+    literal = sql_string_value(expression, interpolation_placeholder=_HOLE)
+    if literal is not None:
+        return literal
+    match expression:
+        case ast.Name():
+            value = _bound_value(expression, context)
+            return _query_text(value, context, seen=seen) if value is not None else None
+        case ast.Call(func=ast.Attribute(attr="format", value=value)):
+            return _query_text(value, context, seen=seen)
+        case ast.Call(func=function, args=[argument], keywords=[]):
+            if context.static_resource_provenance.runtime_import_name(function) == "psycopg.sql.SQL":
+                return _query_text(argument, context, seen=seen)
+        case ast.BinOp(left=left, op=ast.Add(), right=right):
+            left_sql = _query_text(left, context, seen=seen)
+            right_sql = _query_text(right, context, seen=seen)
+            if left_sql is not None or right_sql is not None:
+                return (left_sql or _HOLE) + (right_sql or _HOLE)
+        case _:
+            pass
+    return None
+
+
+def _bound_value(expression: ast.Name, context: PythonFileContext) -> ast.expr | None:
+    provenance = context.static_resource_provenance
+    binding = provenance.runtime_binding(expression.id, expression)
+    return provenance.assignment_value(binding, expression) if isinstance(binding, ast.Name) else None

{sarj_python_lint-1.84.0 → sarj_python_lint-1.85.0}/src/sarj_python_lint/rules/complex_postgres_query_requires_architecture_review.py

@@ -20,6 +20,7 @@ from sarj_python_lint.rules._ast_index import nodes, walk
 from sarj_python_lint.rules._ast_names import unqualified_name as _call_name
 from sarj_python_lint.rules._paths import is_test_path
 from sarj_python_lint.rules._sql import is_store_module, sql_string_value, strip_sql_noise
+from sarj_python_lint.rules._store_sql import relation_key, store_queries
 from sarj_python_lint.rules.no_analytical_aggregation_in_postgres_store import analytical_signal
 
 
@@ -65,6 +66,7 @@ _COMBINED_JOIN_LIMIT = 3
 _COMBINED_STAGE_LIMIT = 4
 _WIDE_PROJECTION_LIMIT = 25
 _WIDE_PROJECTION_JOIN_LIMIT = 2
+_WIDE_SELF_JOIN_PROJECTION_LIMIT = 16
 
 
 class _ConstructorImport(NamedTuple):
@@ -175,14 +177,13 @@ def _recoverable_query_root(node: ast.expr, constructors: frozenset[str]) -> ast
 
 def _qualified_name(node: ast.expr) -> str:
     match node:
-        case ast.Name():
-            return node.id
-        case ast.Attribute():
-            owner = _qualified_name(node.value)
-            return f"{owner}.{node.attr}" if owner else node.attr
+        case ast.Name(id=name):
+            return name
+        case ast.Attribute(value=value, attr=attribute):
+            owner = _qualified_name(value)
+            return f"{owner}.{attribute}" if owner else attribute
         case _:
-            pass
-    return ""
+            return ""
 
 
 def _visible_constructors(
@@ -259,9 +260,9 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only statically recoverable SQL passed to execute, executemany, fetch, fetchrow, fetchval, or prepare in non-test modules with explicit PostgreSQL imports is analyzed, regardless of module filename.",
-            "Execution receivers must use a conventional database name; custom wrappers and dynamically obtained receivers abstain.",
-            "One direct, unambiguous simple-name binding in the same lexical scope is followed; standalone constants, branches, aliases, attributes, containers, wildcard imports, and cross-scope flow abstain.",
-            "Review covers derived relations in every SELECT (including LATERAL, CTEs, predicates and writes), four explicit or comma joins, six query stages, three joins plus four stages, or 25 projections plus two joins.",
+            "Execution receivers use a conventional database name or import-proven Psycopg ownership. Native execution additionally follows stable module/local SQL bindings and direct same-class query-forwarding wrappers; unknown receivers abstain.",
+            "Conventional receivers follow one direct, unambiguous same-scope binding. Native Psycopg recovery may follow bounded stable lexical bindings, including module constants. Unexecuted constants, branch-local assignments, mutable attributes, containers and unknown dynamic composition abstain.",
+            "Review covers derived relations in every SELECT (including LATERAL, CTEs, predicates and writes), four explicit or comma joins, six query stages, three joins plus four stages, or 25 projections plus two joins. A self join over the same explicit table also merits review at 16 projected expressions.",
             "Derived-relation review requires grouping, HAVING or windowing combined with joins or nested reads; expression density is not a separate trigger.",
             "Projection width alone is accepted, and UNION branches are measured independently; execution plans and production cardinality remain authoritative.",
             "ClickHouse and BigQuery syntax is excluded per query, including in mixed-backend modules.",
@@ -352,42 +353,57 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
         if not _is_postgres_module(tree, node_index=context.node_index):
             return []
 
-        docstrings = context.docstring_node_ids
-        parents = context.parents
-        query_roots = _query_roots(tree, parents, node_index=context.node_index)
-        diagnostics: list[Diagnostic] = []
-        consumed: set[int] = set()
-        for node in context.nodes(ast.Constant, ast.BinOp, ast.JoinedStr):
-            if id(node) in consumed or id(node) in docstrings or not _is_query_context(node, parents, query_roots):
-                continue
-            text_value = sql_string_value(node, interpolation_placeholder=_SQL_HOLE)
-            if text_value is None:
-                continue
-            if isinstance(node, (ast.BinOp, ast.JoinedStr)):
-                consumed.update(id(child) for child in walk(node))
-
-            signal = _query_architecture_signal(text_value, path)
+        diagnostics = _conventional_findings(context, self.code)
+        for query in store_queries(context):
+            signal = _query_architecture_signal(query.sql, path)
             if signal is None:
                 continue
-            guidance = _query_review_guidance(text_value)
-            diagnostics.append(
-                Diagnostic(
-                    path=path,
-                    line=node.lineno,
-                    col=node.col_offset + 1,
-                    code=self.code,
-                    severity=Severity.WARNING,
-                    message=(
-                        f"Complex PostgreSQL query: {signal}. Architecture review required;{guidance} "
-                        "Prefer ClickHouse for reporting, historical analysis, and broad aggregations. "
-                        "For transactional work, simplify the query or document why PostgreSQL is required, "
-                        "with query bounds and EXPLAIN evidence. Do not add reporting-specific indexes without "
-                        "evaluating ClickHouse. Syntax alone does not establish runtime cost or datastore placement."
-                    ),
-                )
+            node = query.node
+            diagnostics.append(_native_diagnostic(context, node, signal, self.code, query.sql))
+        unique = {(finding.line, finding.col): finding for finding in diagnostics}
+        return sorted(unique.values(), key=lambda finding: (finding.line, finding.col))
+
+
+def _conventional_findings(context: PythonFileContext, code: str) -> list[Diagnostic]:
+    path = context.path
+    docstrings = context.docstring_node_ids
+    parents = context.parents
+    tree = context.tree
+    if tree is None:
+        return []
+    query_roots = _query_roots(tree, parents, node_index=context.node_index)
+    diagnostics: list[Diagnostic] = []
+    consumed: set[int] = set()
+    for node in context.nodes(ast.Constant, ast.BinOp, ast.JoinedStr):
+        if id(node) in consumed or id(node) in docstrings or not _is_query_context(node, parents, query_roots):
+            continue
+        text_value = sql_string_value(node, interpolation_placeholder=_SQL_HOLE)
+        if text_value is None:
+            continue
+        if isinstance(node, (ast.BinOp, ast.JoinedStr)):
+            consumed.update(id(child) for child in walk(node))
+
+        signal = _query_architecture_signal(text_value, path)
+        if signal is None:
+            continue
+        guidance = _query_review_guidance(text_value)
+        diagnostics.append(
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=code,
+                severity=Severity.WARNING,
+                message=(
+                    f"Complex PostgreSQL query: {signal}. Architecture review required;{guidance} "
+                    "Prefer ClickHouse for reporting, historical analysis, and broad aggregations. "
+                    "For transactional work, simplify the query or document why PostgreSQL is required, "
+                    "with query bounds and EXPLAIN evidence. Do not add reporting-specific indexes without "
+                    "evaluating ClickHouse. Syntax alone does not establish runtime cost or datastore placement."
+                ),
             )
-        diagnostics.sort(key=lambda diagnostic: (diagnostic.line, diagnostic.col))
-        return diagnostics
+        )
+    return diagnostics
 
 
 def _count_query_bindings(
@@ -473,12 +489,13 @@ def _query_architecture_signal(text_value: str, path: Path) -> str | None:
 
 
 def _parse_signal(sql: str) -> str | None:
-    import sqlglot  # ruff: ignore[import-outside-top-level] -- parse only SQL that passes cheap ownership and shape gates
     from sqlglot.errors import SqlglotError  # ruff: ignore[import-outside-top-level] -- paired with lazy parser import
 
+    from sarj_python_lint.rules._postgres import parse_postgres  # ruff: ignore[import-outside-top-level] -- unsupported SQL must not log private source.
+
     normalized = _COMPOSABLE_HOLE.sub(_SQL_HOLE, sql)
     try:
-        for statement in sqlglot.parse(normalized, read="postgres"):
+        for statement in parse_postgres(normalized):
             if statement is not None and (signal := _architecture_signal(statement)) is not None:
                 return signal
     except SqlglotError:
@@ -502,14 +519,45 @@ def _architecture_signal(statement: exp.Expr) -> str | None:
         return f"Query has {nested_queries} CTE/subquery stages"
     if maximum_joins >= _COMBINED_JOIN_LIMIT and nested_queries >= _COMBINED_STAGE_LIMIT:
         return f"Query combines {maximum_joins} JOINs with {nested_queries} CTE/subquery stages"
+    return _projection_width_signal(statement)
+
+
+def _projection_width_signal(statement: exp.Expr) -> str | None:
+    from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- only parsed projection shapes need types.
+
     for select in statement.find_all(exp.Select):
         projections = tuple(_expression_args(select, "expressions"))
         joins = tuple(join for join in _expression_args(select, "joins") if isinstance(join, exp.Join))
         if len(projections) >= _WIDE_PROJECTION_LIMIT and len(joins) >= _WIDE_PROJECTION_JOIN_LIMIT:
             return f"Joined query block has {len(projections)} projected expressions"
+        if len(projections) >= _WIDE_SELF_JOIN_PROJECTION_LIMIT and _self_join(select, joins):
+            return f"Self-joined query block has {len(projections)} projected expressions"
     return None
 
 
+def _native_diagnostic(context: PythonFileContext, node: ast.expr, signal: str, code: str, sql: str) -> Diagnostic:
+    return Diagnostic(
+        context.path,
+        node.lineno,
+        node.col_offset + 1,
+        code,
+        f"Complex PostgreSQL query: {signal}. Architecture review required;{_query_review_guidance(sql)} "
+        "Prefer ClickHouse for reporting, historical analysis, and broad aggregations. "
+        "For transactional work, simplify the query or document why PostgreSQL is required, "
+        "with query bounds and EXPLAIN evidence. Do not add reporting-specific indexes without "
+        "evaluating ClickHouse. Syntax alone does not establish runtime cost or datastore placement.",
+        severity=Severity.WARNING,
+    )
+
+
+def _self_join(select: exp.Select, joins: tuple[exp.Join, ...]) -> bool:
+    from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- compare only literal relation identities.
+
+    from_clause = _expression_arg(select, "from_")
+    root = relation_key(_expression_arg(from_clause, "this")) if isinstance(from_clause, exp.From) else None
+    return root is not None and any(relation_key(_expression_arg(join, "this")) == root for join in joins)
+
+
 def _derived_architecture_signal(statement: exp.Expr) -> str | None:
     from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs