sarj-python-lint 0.42.0__tar.gz → 0.43.0__tar.gz

{sarj_python_lint-0.42.0 → sarj_python_lint-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.42.0
+Version: 0.43.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
 Project-URL: Repository, https://github.com/sarj-ai/standards

{sarj_python_lint-0.42.0 → sarj_python_lint-0.43.0}/pyproject.toml

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

{sarj_python_lint-0.42.0 → sarj_python_lint-0.43.0}/src/sarj_python_lint/rules/_registry.py

@@ -75,6 +75,7 @@ from sarj_python_lint.rules.prefer_module_level_constant import (
 from sarj_python_lint.rules.prefer_namedtuple_over_tuple_return import (
     PreferNamedtupleOverTupleReturn,
 )
+from sarj_python_lint.rules.prefer_nominal_id_types import PreferNominalIdTypes
 from sarj_python_lint.rules.prefer_non_nullable_collection import (
     PreferNonNullableCollection,
 )
@@ -196,6 +197,7 @@ REGISTRY: dict[str, type[Rule]] = {
     PreferSingleSentenceComment.id: PreferSingleSentenceComment,
     NoLongComment.id: NoLongComment,
     NoTypedDocSections.id: NoTypedDocSections,
+    PreferNominalIdTypes.id: PreferNominalIdTypes,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.43.0/src/sarj_python_lint/rules/prefer_nominal_id_types.py

@@ -0,0 +1,219 @@
+"""SARJ093 flags boundaries where multiple ID roles share primitive string types.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_prefer_nominal_id_types.py
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, is_suppressed, parse_or_none
+from sarj_python_lint.rules._ast_index import walk
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_TRANSPARENT_WRAPPERS = frozenset({"List", "Mapped", "Optional", "Sequence", "list"})
+_UNION_WRAPPERS = frozenset({"Union"})
+_MIN_ID_ROLES = 2
+_OPERATIONAL_IDS = frozenset(
+    {
+        "correlation_id",
+        "event_id",
+        "job_id",
+        "message_id",
+        "operation_id",
+        "request_id",
+        "span_id",
+        "task_id",
+        "trace_id",
+        "unique_id",
+    }
+)
+_MIGRATION_PARTS = frozenset({"alembic", "migrations", "versions"})
+_NON_PRODUCTION_PARTS = frozenset({"fixtures", "scripts", "test_fakes", "testing"})
+_RAW_SCHEMA_SUFFIXES = ("Config", "Credentials", "Settings")
+
+
+@dataclass(frozen=True, slots=True)
+class _IdRole:
+    name: str
+    annotation: ast.expr
+    raw_string: bool
+
+
+class PreferNominalIdTypes(Rule):
+    id: str = "prefer-nominal-id-types"
+    code: str = "SARJ093"
+    description: str = (
+        "A production boundary with multiple ID-shaped roles should use nominal ID types, not primitive strings."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if (
+            is_test_path(path)
+            or is_generated(path, source)
+            or any(part.lower() in _MIGRATION_PARTS for part in path.parts)
+            or any(part.lower() in _NON_PRODUCTION_PARTS for part in path.parts)
+            or _is_external_adapter_path(path)
+        ):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+
+        source_lines = source.splitlines()
+        diagnostics: list[Diagnostic] = []
+        exempt_schema_nodes = {
+            descendant
+            for candidate in ast.walk(tree)
+            if isinstance(candidate, ast.ClassDef) and _is_raw_schema_class(candidate)
+            for descendant in ast.walk(candidate)
+            if descendant is not candidate
+        }
+        for node in walk(tree):
+            if node in exempt_schema_nodes:
+                continue
+            roles = _boundary_roles(node)
+            raw = [role for role in roles if role.raw_string]
+            if not raw or len({role.name for role in roles}) < _MIN_ID_ROLES:
+                continue
+            first = raw[0]
+            if is_suppressed(source_lines, first.annotation.lineno, self.code):
+                continue
+            names = ", ".join(f"`{role.name}`" for role in roles)
+            diagnostics.append(
+                Diagnostic(
+                    path=path,
+                    line=first.annotation.lineno,
+                    col=first.annotation.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"{names} are multiple ID-shaped roles at one boundary, but at least one uses primitive `str`; "
+                        "introduce or reuse `NewType` identifier types and propagate them through the boundary."
+                    ),
+                )
+            )
+        return sorted(diagnostics, key=lambda diagnostic: (diagnostic.line, diagnostic.col))
+
+
+def _boundary_roles(node: ast.AST) -> list[_IdRole]:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        if node.name.startswith("_") and node.name != "__init__":
+            return []
+        arguments = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]
+        return [role for argument in arguments if (role := _role(argument.arg, argument.annotation)) is not None]
+    if isinstance(node, ast.ClassDef):
+        if _is_raw_schema_class(node):
+            return []
+        return [
+            role
+            for statement in node.body
+            if isinstance(statement, ast.AnnAssign) and isinstance(statement.target, ast.Name)
+            if (role := _role(statement.target.id, statement.annotation, allow_bare_id=True)) is not None
+        ]
+    return []
+
+
+def _role(name: str, annotation: ast.expr | None, *, allow_bare_id: bool = False) -> _IdRole | None:
+    if annotation is None or name in _OPERATIONAL_IDS:
+        return None
+    if not (name.endswith(("_id", "_ids")) or (allow_bare_id and name == "id")):
+        return None
+    raw_string = _is_raw_string_id(annotation)
+    if not raw_string and not _is_nominal_id(annotation):
+        return None
+    return _IdRole(name=name, annotation=annotation, raw_string=raw_string)
+
+
+def _qualified_tail(node: ast.expr) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""
+
+
+def _is_raw_schema_class(node: ast.ClassDef) -> bool:
+    return node.name.endswith(_RAW_SCHEMA_SUFFIXES) or any(
+        _qualified_tail(base) == "Protocol" for base in node.bases
+    )
+
+
+def _is_external_adapter_path(path: Path) -> bool:
+    parts = {part.lower() for part in path.parts}
+    return "providers" in parts or "integration" in parts or (
+        "integrations" in parts and ("models" in parts or path.name == "models.py")
+    )
+
+
+def _is_raw_string_id(annotation: ast.expr) -> bool:
+    if isinstance(annotation, ast.Name):
+        return annotation.id == "str"
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        members = _flatten_union(annotation)
+        return any(_is_raw_string_id(member) for member in members) and all(
+            _is_raw_string_id(member) or _is_nominal_id(member) or _is_none(member)
+            for member in members
+        )
+    if not isinstance(annotation, ast.Subscript):
+        return False
+    wrapper = _qualified_tail(annotation.value)
+    if wrapper == "Annotated":
+        return (
+            isinstance(annotation.slice, ast.Tuple)
+            and bool(annotation.slice.elts)
+            and _is_raw_string_id(annotation.slice.elts[0])
+        )
+    if wrapper in _TRANSPARENT_WRAPPERS:
+        return _is_raw_string_id(annotation.slice)
+    if wrapper in _UNION_WRAPPERS:
+        members = list(annotation.slice.elts) if isinstance(annotation.slice, ast.Tuple) else [annotation.slice]
+        return any(_is_raw_string_id(member) for member in members) and all(
+            _is_raw_string_id(member) or _is_nominal_id(member) or _is_none(member)
+            for member in members
+        )
+    return False
+
+
+def _flatten_union(annotation: ast.expr) -> list[ast.expr]:
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        return [*_flatten_union(annotation.left), *_flatten_union(annotation.right)]
+    return [annotation]
+
+
+def _is_none(annotation: ast.expr) -> bool:
+    return (isinstance(annotation, ast.Constant) and annotation.value is None) or (
+        isinstance(annotation, ast.Name) and annotation.id == "None"
+    )
+
+
+def _is_nominal_id(annotation: ast.expr) -> bool:
+    if isinstance(annotation, (ast.Name, ast.Attribute)):
+        tail = _qualified_tail(annotation)
+        return tail.endswith(("Id", "ID"))
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        members = _flatten_union(annotation)
+        return any(_is_nominal_id(member) for member in members) and all(
+            _is_nominal_id(member) or _is_none(member) for member in members
+        )
+    if isinstance(annotation, ast.Subscript) and _qualified_tail(annotation.value) in _TRANSPARENT_WRAPPERS:
+        return _is_nominal_id(annotation.slice)
+    if (
+        isinstance(annotation, ast.Subscript)
+        and _qualified_tail(annotation.value) == "Annotated"
+        and isinstance(annotation.slice, ast.Tuple)
+    ):
+        return bool(annotation.slice.elts) and _is_nominal_id(annotation.slice.elts[0])
+    if isinstance(annotation, ast.Subscript) and _qualified_tail(annotation.value) in _UNION_WRAPPERS:
+        members = list(annotation.slice.elts) if isinstance(annotation.slice, ast.Tuple) else [annotation.slice]
+        return any(_is_nominal_id(member) for member in members) and all(
+            _is_nominal_id(member) or _is_none(member) for member in members
+        )
+    return False