sarj-python-lint 0.83.1__tar.gz → 0.84.1__tar.gz

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/PKG-INFO

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

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

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/__main__.py

@@ -209,7 +209,7 @@ def _suppressed_diagnostics(
 
 
 def _suppressed_codes(codes: dict[str, set[Severity]]) -> set[tuple[str, Severity]]:
-    return {
+    suppressed = {
         (generic, generic_severity)
         for specific, generics in _DIAGNOSTIC_PRECEDENCE.items()
         if specific in codes
@@ -217,6 +217,13 @@ def _suppressed_codes(codes: dict[str, set[Severity]]) -> set[tuple[str, Severit
         for generic_severity in codes.get(generic, set())
         if generic_severity is Severity.WARNING or Severity.ERROR in codes[specific]
     }
+    # The promoted signature-restatement rules now block. Keep their errors and
+    # drop only the lower-severity typed-docstring twin at the same owner.
+    if Severity.WARNING in codes.get("SARJ092", set()) and any(
+        Severity.ERROR in codes.get(generic, set()) for generic in ("SARJ086", "SARJ087")
+    ):
+        suppressed.add(("SARJ092", Severity.WARNING))
+    return suppressed
 
 
 def _function_signature_owner_locations(source: str) -> dict[int, _OwnerLocation]:

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/_registry.py

@@ -15,6 +15,7 @@ from sarj_python_lint.rules.docstring_returns_restate_signature import (
 )
 from sarj_python_lint.rules.excessive_commentary import ExcessiveCommentary
 from sarj_python_lint.rules.fakes_in_shared_location import FakesInSharedLocation
+from sarj_python_lint.rules.fastapi_class_router_contract import FastapiClassRouterContract
 from sarj_python_lint.rules.fastapi_explicit_openapi_contract import FastapiExplicitOpenapiContract
 from sarj_python_lint.rules.iac_source_coupled_test import IacSourceCoupledTest
 from sarj_python_lint.rules.invalid_pydantic_field_default import (
@@ -51,6 +52,7 @@ from sarj_python_lint.rules.no_generic_single_export_module import NoGenericSing
 from sarj_python_lint.rules.no_hidden_constructor_fallback import (
     NoHiddenConstructorFallback,
 )
+from sarj_python_lint.rules.no_invalid_argument_name_suppression import NoInvalidArgumentNameSuppression
 from sarj_python_lint.rules.no_nested_pydantic_field_validator import NoNestedPydanticFieldValidator
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
 from sarj_python_lint.rules.no_positional_psycopg_row_escape import NoPositionalPsycopgRowEscape
@@ -75,6 +77,7 @@ from sarj_python_lint.rules.no_unique_violation_message_match import (
     NoUniqueViolationMessageMatch,
 )
 from sarj_python_lint.rules.no_unnecessary_docstring import NoUnnecessaryDocstring
+from sarj_python_lint.rules.no_vague_annotations import NoVagueAnnotations
 from sarj_python_lint.rules.no_vague_suppression_description import (
     NoVagueSuppressionDescription,
 )
@@ -147,9 +150,11 @@ from sarj_python_lint.rules.require_port_for_service import RequirePortForServic
 from sarj_python_lint.rules.require_pydantic_for_external_json import (
     RequirePydanticForExternalJson,
 )
+from sarj_python_lint.rules.require_pydantic_for_structured_payload import RequirePydanticForStructuredPayload
 from sarj_python_lint.rules.require_pydantic_ordinal_lower_bound import (
     RequirePydanticOrdinalLowerBound,
 )
+from sarj_python_lint.rules.require_typed_http_test_response import RequireTypedHttpTestResponse
 from sarj_python_lint.rules.restated_test_docstring import RestatedTestDocstring
 from sarj_python_lint.rules.stepdown import Stepdown
 from sarj_python_lint.rules.store_get_delegates_to_bulk_read import StoreGetDelegatesToBulkRead
@@ -185,6 +190,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoCorsWildcardWithCredentials.id: NoCorsWildcardWithCredentials,
         PydanticAtBoundaries.id: PydanticAtBoundaries,
         FastapiExplicitOpenapiContract.id: FastapiExplicitOpenapiContract,
+        FastapiClassRouterContract.id: FastapiClassRouterContract,
         FakesInSharedLocation.id: FakesInSharedLocation,
         PreferConstantTimeSecretCompare.id: PreferConstantTimeSecretCompare,
         NoSecretInLog.id: NoSecretInLog,
@@ -222,6 +228,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoRedundantModuleAliasExports.id: NoRedundantModuleAliasExports,
         NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
         NoFileLevelEscapeHatchSuppression.id: NoFileLevelEscapeHatchSuppression,
+        NoInvalidArgumentNameSuppression.id: NoInvalidArgumentNameSuppression,
         NoFastapiOnEvent.id: NoFastapiOnEvent,
         NoTautologicalExpect.id: NoTautologicalExpect,
         PreferLibraryFake.id: PreferLibraryFake,
@@ -258,6 +265,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoTypedDocSections.id: NoTypedDocSections,
         NoUnnecessaryDocstring.id: NoUnnecessaryDocstring,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
+        NoVagueAnnotations.id: NoVagueAnnotations,
         NoUniqueViolationMessageMatch.id: NoUniqueViolationMessageMatch,
         NegativeOnlyHttpStatusAssertion.id: NegativeOnlyHttpStatusAssertion,
         ProductionDerivedTestCases.id: ProductionDerivedTestCases,
@@ -266,6 +274,8 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoPositionalPsycopgRowEscape.id: NoPositionalPsycopgRowEscape,
         NoPsycopgExecutionOutsideInjectedOwner.id: NoPsycopgExecutionOutsideInjectedOwner,
         RequirePydanticOrdinalLowerBound.id: RequirePydanticOrdinalLowerBound,
+        RequirePydanticForStructuredPayload.id: RequirePydanticForStructuredPayload,
+        RequireTypedHttpTestResponse.id: RequireTypedHttpTestResponse,
         RequireNoDecodeForSplittingSettingsField.id: RequireNoDecodeForSplittingSettingsField,
         NoVagueSuppressionDescription.id: NoVagueSuppressionDescription,
         NoWholeRequestResponsePayloadInLog.id: NoWholeRequestResponsePayloadInLog,

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/docstring_args_restate_signature.py

@@ -181,7 +181,7 @@ class DocstringArgsRestateSignature(Rule):
                     f"`{node.name}` has an Args section whose entries only repeat matching parameter names or types; "
                     "remove that section or document a constraint not evident from the signature."
                 ),
-                severity=Severity.WARNING,
+                severity=Severity.ERROR,
             )
         )
 

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/docstring_returns_restate_signature.py

@@ -252,7 +252,7 @@ class DocstringReturnsRestateSignature(Rule):
                     f"`{node.name}` {section.name} section only repeats its callable name or annotated result type; "
                     "remove that section or document result semantics not expressed by the signature."
                 ),
-                severity=Severity.WARNING,
+                severity=Severity.ERROR,
             )
         )
 

sarj_python_lint-0.84.1/src/sarj_python_lint/rules/fastapi_class_router_contract.py

@@ -0,0 +1,191 @@
+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,
+    parse_or_none,
+)
+from sarj_python_lint.rules._fastapi import FastapiIndex, Route, flat_name
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_NO_BODY = frozenset({204, 304})
+_NON_JSON_RESPONSES = frozenset(
+    {"FileResponse", "HTMLResponse", "PlainTextResponse", "RedirectResponse", "StreamingResponse"}
+)
+_TOP_LEVEL_COLLECTIONS = frozenset(
+    {"dict", "Dict", "list", "List", "Mapping", "MutableMapping", "set", "Set", "tuple", "Tuple", "Sequence"}
+)
+_SCALARS = frozenset({"bool", "bytes", "float", "int", "str"})
+
+
+@final
+class FastapiClassRouterContract(Rule):
+    id = "fastapi-class-router-contract"
+    code = "SARJ451"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="FastAPI routers use injected `*Router.build()` owners and explicit named object response models.",
+        rationale=(
+            "Class-owned construction gives dependencies one reviewable composition boundary, while explicit object models "
+            "keep success envelopes stable and generated clients precise."
+        ),
+        remediation=(
+            "Inject dependencies through `*Router.__init__`, create and return a local `APIRouter` from `build()`, and declare "
+            "`response_model=NamedResponse` with a matching named return annotation."
+        ),
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Tests, generated code, hidden routes, 204/304 responses, and explicit stream/file/HTML/text/redirect responses are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="module-router",
+                title="A module owns an unscoped router",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/routes.py", "from fastapi import APIRouter\nrouter = APIRouter()\n"),),
+                focus_path=PurePosixPath("app/routes.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="class-router",
+                title="A class builds and returns its router",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/routes.py",
+                        "from fastapi import APIRouter\nclass ItemRouter:\n    def __init__(self, service: Service) -> None:\n        self._service = service\n    def build(self) -> APIRouter:\n        router = APIRouter()\n        return router\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/routes.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_test_path(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        index = FastapiIndex(tree, path=path)
+        parents = _parents(tree)
+        findings = _router_construction_findings(path, tree, index, parents)
+        for function in (node for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))):
+            routes = tuple(route for route in index.routes(function) if not route.is_hidden)
+            for route in routes:
+                problem = _response_problem(function, route, index)
+                if problem is not None:
+                    findings.append(Diagnostic(path, function.lineno, function.col_offset + 1, self.code, problem))
+        return sorted(findings, key=lambda finding: (finding.line, finding.col, finding.message))
+
+
+def _router_construction_findings(
+    path: Path, tree: ast.Module, index: FastapiIndex, parents: dict[int, ast.AST]
+) -> list[Diagnostic]:
+    findings: list[Diagnostic] = []
+    for call in (node for node in ast.walk(tree) if isinstance(node, ast.Call)):
+        if index.canonical(call.func) != "APIRouter":
+            continue
+        function = _ancestor(call, parents, (ast.FunctionDef, ast.AsyncFunctionDef))
+        cls = _ancestor(call, parents, ast.ClassDef)
+        if (
+            isinstance(function, (ast.FunctionDef, ast.AsyncFunctionDef))
+            and isinstance(cls, ast.ClassDef)
+            and function.name == "build"
+            and cls.name.endswith("Router")
+            and _returns_local_router(function, call)
+        ):
+            continue
+        findings.append(
+            Diagnostic(
+                path,
+                call.lineno,
+                call.col_offset + 1,
+                FastapiClassRouterContract.code,
+                "construct APIRouter only inside `*Router.build()` and return that local router",
+            )
+        )
+    return findings
+
+
+def _returns_local_router(function: ast.FunctionDef | ast.AsyncFunctionDef, call: ast.Call) -> bool:
+    names = {
+        target.id
+        for node in function.body
+        if isinstance(node, (ast.Assign, ast.AnnAssign))
+        for target in _assignment_targets(node)
+        if isinstance(target, ast.Name) and getattr(node, "value", None) is call
+    }
+    return bool(names) and any(
+        isinstance(node, ast.Return) and isinstance(node.value, ast.Name) and node.value.id in names
+        for node in function.body
+    )
+
+
+def _assignment_targets(node: ast.Assign | ast.AnnAssign) -> list[ast.expr]:
+    return list(node.targets) if isinstance(node, ast.Assign) else [node.target]
+
+
+def _response_problem(
+    function: ast.FunctionDef | ast.AsyncFunctionDef, route: Route, index: FastapiIndex
+) -> str | None:
+    keywords = route.keywords
+    status = keywords.get("status_code")
+    if isinstance(status, ast.Constant) and status.value in _NO_BODY:
+        return None
+    response_class = keywords.get("response_class") or route.inherited_response_class
+    if response_class is not None and flat_name(response_class) in _NON_JSON_RESPONSES:
+        return None
+    response_model = keywords.get("response_model")
+    if response_model is None or (isinstance(response_model, ast.Constant) and response_model.value is None):
+        return "JSON operation requires explicit `response_model=NamedResponse`"
+    annotation = index.resolve_annotation(function.returns)
+    if annotation is None:
+        return "JSON operation requires a named response return annotation matching response_model"
+    if _is_collection_or_scalar(annotation):
+        return (
+            "successful JSON responses must use a named object envelope, not a top-level collection, mapping, or scalar"
+        )
+    if flat_name(annotation) != flat_name(response_model):
+        return "response_model must match the named response return annotation"
+    return None
+
+
+def _is_collection_or_scalar(annotation: ast.expr) -> bool:
+    target = annotation.value if isinstance(annotation, ast.Subscript) else annotation
+    return flat_name(target) in _TOP_LEVEL_COLLECTIONS | _SCALARS
+
+
+def _parents(tree: ast.Module) -> dict[int, ast.AST]:
+    return {id(child): parent for parent in ast.walk(tree) for child in ast.iter_child_nodes(parent)}
+
+
+def _ancestor(
+    node: ast.AST, parents: dict[int, ast.AST], kind: type[ast.AST] | tuple[type[ast.AST], ...]
+) -> ast.AST | None:
+    current = parents.get(id(node))
+    while current is not None:
+        if isinstance(current, kind):
+            return current
+        current = parents.get(id(current))
+    return None

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/no_copied_inherited_docstring.py

@@ -158,7 +158,7 @@ class NoCopiedInheritedDocstring(Rule):
                         f"Docstring has the same cleaned content as {parent.name}.{name}'s. Remove it only if no "
                         "consumer requires the override's direct `__doc__`; otherwise retain it with a narrow rationale."
                     ),
-                    severity=Severity.WARNING,
+                    severity=Severity.ERROR,
                 )
             )
 

sarj_python_lint-0.84.1/src/sarj_python_lint/rules/no_invalid_argument_name_suppression.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+import re
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    ColumnEncoding,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+)
+from sarj_python_lint.rules._paths import is_generated
+from sarj_python_lint.rules._suppression_comments import scan_comments_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_FORBIDDEN = re.compile(r"(?:^|[,:\s\[])\s*(?:N803|invalid-argument-name)(?=$|[,\]\s])", re.IGNORECASE)
+
+
+@final
+class NoInvalidArgumentNameSuppression(Rule):
+    id = "no-invalid-argument-name-suppression"
+    code = "SARJ448"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="External parameter spelling must use framework aliases instead of disabling snake_case naming.",
+        rationale="Naming suppressions leak an external wire vocabulary into Python APIs and normalize future exceptions.",
+        remediation=(
+            "Keep the Python parameter snake_case and preserve the external spelling with FastAPI `Query`/`Path` aliases "
+            "or Pydantic `Field` aliases."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        limitations=("Generated source is excluded.",),
+        examples=(
+            RuleExample(
+                example_id="camel-case-parameter-suppression",
+                title="A wire parameter disables Python naming",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/routes.py",
+                        "def route(businessFunction: str):  # ruff: ignore[invalid-argument-name]\n    ...\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/routes.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="snake-case-wire-alias",
+                title="A framework alias preserves external spelling",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/routes.py",
+                        "from fastapi import Query\ndef route(business_function: str = Query(alias='businessFunction')): ...\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/routes.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated(path, source):
+            return []
+        comments = scan_comments_or_none(source)
+        if comments is None:
+            return []
+        return [
+            Diagnostic(
+                path=path,
+                line=comment.line,
+                col=comment.col,
+                code=self.code,
+                message=(
+                    "do not suppress Python argument naming; use a snake_case parameter and an explicit wire alias"
+                ),
+                column_encoding=ColumnEncoding.CODEPOINTS,
+            )
+            for comment in comments
+            if _FORBIDDEN.search(comment.body)
+        ]

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/no_repeated_string_literal.py

@@ -187,7 +187,7 @@ class NoRepeatedStringLiteral(Rule):
                             f"structured string literal {_preview(value)} duplicates module constant "
                             f"`{constant_name}` — reuse the canonical constant so the copies cannot drift."
                         ),
-                        severity=Severity.WARNING,
+                        severity=Severity.ERROR,
                     )
                     for node in function_nodes
                 )
@@ -209,7 +209,7 @@ class NoRepeatedStringLiteral(Rule):
                         f"callable scopes (first use at line {first.lineno}) — reuse a named binding "
                         "when they share ownership, or suppress with an independent-ownership rationale."
                     ),
-                    severity=Severity.WARNING,
+                    severity=Severity.ERROR,
                 )
                 for node in repeats
             )

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/no_repeated_test_body.py

@@ -204,7 +204,7 @@ class NoRepeatedTestBody(Rule):
                 col=group[1].node.col_offset + 1,
                 code=self.code,
                 message=_message(group),
-                severity=Severity.WARNING,
+                severity=Severity.ERROR,
             )
             for group in groups
         ]

sarj_python_lint-0.84.1/src/sarj_python_lint/rules/no_vague_annotations.py

@@ -0,0 +1,173 @@
+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,
+    is_suppressed,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
+_MAPPING_SOURCES = frozenset({"collections.abc", "typing"})
+_MAPPING_NAMES = frozenset({"dict", "Dict", "Mapping", "MutableMapping"})
+_MAPPING_ARGUMENT_COUNT = 2
+
+
+@final
+class NoVagueAnnotations(Rule):
+    id = "no-vague-annotations"
+    code = "SARJ447"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Annotations must not erase domain shape with `object` or `dict[str, Any]`.",
+        rationale=(
+            "Vague annotations move schema mistakes from type checking to runtime and conceal the fields a caller may use."
+        ),
+        remediation=(
+            "Use a named Pydantic model, dataclass, TypedDict, Protocol, TypeVar, domain type, or an explicit recursive "
+            "JSON value type at a serialization boundary."
+        ),
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=("Generated and vendored sources are excluded; exact local suppressions remain auditable.",),
+        examples=(
+            RuleExample(
+                example_id="vague-mapping-annotation",
+                title="An open mapping erases the record schema",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/offers.py", "from typing import Any\ndef details() -> dict[str, Any]: ...\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("app/offers.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="named-model-annotation",
+                title="A named model preserves the record schema",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/offers.py", "def details() -> OfferDetails: ...\n"),),
+                focus_path=PurePosixPath("app/offers.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated(path, source) or _is_vendor_path(path):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree)
+        lines = source.splitlines()
+        findings: list[Diagnostic] = []
+        for annotation in _annotations(tree):
+            problem = _vague_problem(annotation, imports)
+            if problem is None or is_suppressed(lines, annotation.lineno, self.code):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=path,
+                    line=annotation.lineno,
+                    col=annotation.col_offset + 1,
+                    code=self.code,
+                    message=f"vague annotation `{problem}` erases its domain schema; use a named precise type",
+                )
+            )
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+def _annotations(tree: ast.Module) -> list[ast.expr]:
+    return [annotation for node in ast.walk(tree) if (annotation := _node_annotation(node)) is not None]
+
+
+def _node_annotation(node: ast.AST) -> ast.expr | None:
+    match node:
+        case (
+            ast.arg(annotation=annotation)
+            | ast.AnnAssign(annotation=annotation)
+            | ast.FunctionDef(returns=annotation)
+            | ast.AsyncFunctionDef(returns=annotation)
+        ):
+            return annotation
+        case ast.TypeAlias(value=value):
+            return value
+        case _:
+            return None
+
+
+def _vague_problem(annotation: ast.expr, imports: ImportIndex) -> str | None:
+    annotation = _parse_string_annotation(annotation)
+    for node in ast.walk(annotation):
+        if _is_object(node, imports):
+            return "object"
+        if _is_open_mapping(node, imports):
+            return ast.unparse(node)
+    return None
+
+
+def _parse_string_annotation(annotation: ast.expr) -> ast.expr:
+    if not isinstance(annotation, ast.Constant) or not isinstance(annotation.value, str):
+        return annotation
+    try:
+        return ast.parse(annotation.value, mode="eval").body
+    except SyntaxError:
+        return annotation
+
+
+def _is_object(node: ast.AST, imports: ImportIndex) -> bool:
+    return isinstance(node, ast.expr) and (
+        (isinstance(node, ast.Name) and node.id == "object" and imports.builtin_is_unshadowed("object"))
+        or imports.resolves(node, sources=frozenset({"builtins"}), symbol="object")
+    )
+
+
+def _is_open_mapping(node: ast.AST, imports: ImportIndex) -> bool:
+    if (
+        not isinstance(node, ast.Subscript)
+        or not isinstance(node.slice, ast.Tuple)
+        or len(node.slice.elts) != _MAPPING_ARGUMENT_COUNT
+    ):
+        return False
+    target = node.value
+    mapping = (isinstance(target, ast.Name) and target.id == "dict" and imports.builtin_is_unshadowed("dict")) or any(
+        imports.resolves(target, sources=_MAPPING_SOURCES, symbol=name) for name in _MAPPING_NAMES
+    )
+    if not mapping:
+        return False
+    key, value = node.slice.elts
+    return _is_builtin_str(key, imports) and _is_any_or_object(value, imports)
+
+
+def _is_builtin_str(node: ast.expr, imports: ImportIndex) -> bool:
+    return isinstance(node, ast.Name) and node.id == "str" and imports.builtin_is_unshadowed("str")
+
+
+def _is_any_or_object(node: ast.expr, imports: ImportIndex) -> bool:
+    return _is_object(node, imports) or imports.resolves(node, sources=_TYPING_SOURCES, symbol="Any")
+
+
+def _is_vendor_path(path: Path) -> bool:
+    return any(part.casefold() in {"vendor", "vendored", "third_party"} for part in path.parts)

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/no_vague_suppression_description.py

@@ -123,7 +123,7 @@ class NoVagueSuppressionDescription(Rule):
                     message=(
                         f'Suppression reason "{vague_reason}" is generic; name the concrete mismatch or safety invariant.'
                     ),
-                    severity=Severity.WARNING,
+                    severity=Severity.ERROR,
                     column_encoding=ColumnEncoding.CODEPOINTS,
                 )
             )

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/phase_label_comment.py

@@ -112,7 +112,7 @@ class TestPhaseLabelComment(Rule):
                     f"Bare test phase comment {body.strip()!r} narrates structure; delete it or replace it "
                     "with non-obvious rationale."
                 ),
-                severity=Severity.WARNING,
+                severity=Severity.ERROR,
                 column_encoding=ColumnEncoding.CODEPOINTS,
             )
             for line, col, body in standalone

{sarj_python_lint-0.83.1 → sarj_python_lint-0.84.1}/src/sarj_python_lint/rules/prefer_class_row.py

@@ -123,7 +123,7 @@ class PreferClassRow(Rule):
                         line=cursor.factory.lineno,
                         col=cursor.factory.col_offset + 1,
                         code=self.code,
-                        severity=Severity.WARNING,
+                        severity=Severity.ERROR,
                         message=(
                             f"this dict row is immediately converted to `{model}`; use `class_row({model})` to "
                             "construct it during fetch"