sarj-python-lint 0.71.0__tar.gz → 0.72.0__tar.gz

{sarj_python_lint-0.71.0 → sarj_python_lint-0.72.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.71.0
+Version: 0.72.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-0.71.0 → sarj_python_lint-0.72.0}/pyproject.toml

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

{sarj_python_lint-0.71.0 → sarj_python_lint-0.72.0}/src/sarj_python_lint/__main__.py

@@ -13,9 +13,10 @@ from typing import NamedTuple
 
 from sarj_python_lint import __version__
 from sarj_python_lint._filesystem import atomic_write_text
-from sarj_python_lint.rule_base import Diagnostic, Severity, is_suppressed
+from sarj_python_lint.rule_base import Diagnostic, ProjectRule, Severity, is_suppressed
 from sarj_python_lint.rules import REGISTRY
 from sarj_python_lint.rules._paths import clear_path_caches
+from sarj_python_lint.rules._project_index import ProjectIndexSet
 
 
 SKIP_DIR_NAMES = frozenset(
@@ -80,12 +81,19 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
     rules = [REGISTRY[rid]() for rid in rule_ids]
     clear_path_caches()
     expanded = _expand_paths(paths)
-    diags: list[Diagnostic] = []
-    for p in expanded:
+    loaded: dict[Path, str] = {}
+    for path in expanded:
         try:
-            source = p.read_text(encoding="utf-8", errors="replace")
+            loaded[path] = path.read_text(encoding="utf-8", errors="replace")
         except OSError:
             continue
+    project_rules = [rule for rule in rules if isinstance(rule, ProjectRule)]
+    if project_rules:
+        indexes = ProjectIndexSet.build(expanded, loaded)
+        for rule in project_rules:
+            rule.prepare(indexes)
+    diags: list[Diagnostic] = []
+    for p, source in loaded.items():
         source_lines = source.splitlines()
         raw = [diagnostic for rule in rules for diagnostic in rule.check(p, source)]
         diags.extend(

{sarj_python_lint-0.71.0 → sarj_python_lint-0.72.0}/src/sarj_python_lint/rule_base.py

@@ -14,6 +14,8 @@ from typing import TYPE_CHECKING, ClassVar, Final, Self
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
+    from sarj_python_lint.rules._project_index import ProjectIndexSet
+
 
 # Each rule points directly to its executable examples.
 REPO_BLOB: Final = "https://github.com/sarj-ai/standards/blob/main"
@@ -309,6 +311,16 @@ class Rule(ABC):
         return () if spec is None else spec.public_examples
 
 
+class ProjectRule(Rule):
+    """A rule that may resolve first-party symbols prepared once per CLI run."""
+
+    _project_indexes: ProjectIndexSet | None = None
+
+    def prepare(self, indexes: ProjectIndexSet) -> None:
+        """Attach immutable project symbols before checking the selected files."""
+        self._project_indexes = indexes
+
+
 _last_parse: tuple[str, str, ast.Module | None] | None = None
 
 

{sarj_python_lint-0.71.0 → sarj_python_lint-0.72.0}/src/sarj_python_lint/rules/_first_party.py

@@ -126,6 +126,11 @@ def has_first_party_source(module: str, path: Path) -> bool:
     )
 
 
+def project_root(path: Path) -> Path | None:
+    """Return the conservative repository/workspace root used by project-aware rules."""
+    return _project_root(path)
+
+
 def _declares_module(package_dir: Path, segments: list[str]) -> bool:
     target = package_dir.joinpath(*segments)
     try:

sarj_python_lint-0.72.0/src/sarj_python_lint/rules/_project_index.py

@@ -0,0 +1,366 @@
+"""Bounded, run-scoped first-party symbol index for project-aware rules."""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Mapping
+from contextlib import suppress
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import re
+from types import MappingProxyType
+from typing import TYPE_CHECKING, final
+
+from sarj_python_lint.rules._first_party import project_root
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+    from typing import Self
+
+
+_SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        "site-packages",
+        "vendor",
+        "vendored",
+        "venv",
+    }
+)
+_MAX_ROOTS = 8
+_MAX_DIRS_PER_ROOT = 3_000
+_MAX_FILES_PER_ROOT = 10_000
+_MAX_FILE_BYTES = 500_000
+_NEW_TYPE_MIN_ARGS = 2
+_MATCH_CLASS_RE: re.Pattern[str] = re.compile(r"\bcase\s+([A-Z][A-Za-z0-9_]*)\s*\(")
+
+
+@dataclass(frozen=True, slots=True)
+class SymbolRef:
+    module: str
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class ClassSummary:
+    symbol: SymbolRef
+    fields: Mapping[str, ast.expr]
+    is_enum: bool
+
+
+@dataclass(frozen=True, slots=True)
+class SourceUnit:
+    path: Path
+    module: str | None
+    source: str
+    tree: ast.Module | None
+    imports: Mapping[str, SymbolRef]
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedSource:
+    path: Path
+    source: str
+
+
+@final
+class ProjectIndexSet:
+    """Immutable summaries for every bounded first-party root in one lint run."""
+
+    def __init__(self, units: Mapping[Path, SourceUnit]) -> None:
+        self._units = MappingProxyType(dict(units))
+        by_module = {unit.module: unit for unit in units.values() if unit.module is not None}
+        self._by_module = MappingProxyType(by_module)
+        classes: dict[SymbolRef, ClassSummary] = {}
+        nominals: dict[str, set[SymbolRef]] = {}
+        for unit in units.values():
+            if unit.module is None or unit.tree is None:
+                continue
+            for statement in unit.tree.body:
+                if isinstance(statement, ast.ClassDef):
+                    symbol = SymbolRef(unit.module, statement.name)
+                    fields = {
+                        item.target.id: item.annotation
+                        for item in statement.body
+                        if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name)
+                    }
+                    classes[symbol] = ClassSummary(
+                        symbol=symbol,
+                        fields=MappingProxyType(fields),
+                        is_enum=any(_tail(base) in {"Enum", "IntEnum", "StrEnum"} for base in statement.bases),
+                    )
+                nominal = _new_type(statement, unit.module)
+                if nominal is not None:
+                    nominals.setdefault(_field_key(nominal.name), set()).add(nominal)
+        self._classes = MappingProxyType(classes)
+        self._nominals = MappingProxyType({key: frozenset(value) for key, value in nominals.items()})
+
+    @classmethod
+    def build(cls, paths: Sequence[Path], loaded: Mapping[Path, str]) -> Self:
+        roots = _project_roots(paths)
+        sources: dict[Path, str] = {}
+        for path, source in loaded.items():
+            try:
+                sources[path.resolve()] = source
+            except OSError:
+                continue
+        for root in roots:
+            count = 0
+            for path in _python_files(root):
+                if count >= _MAX_FILES_PER_ROOT:
+                    break
+                try:
+                    if path.resolve() in sources:
+                        count += 1
+                        continue
+                except OSError:
+                    continue
+                loaded_source = _read_bounded_source(root, path)
+                if loaded_source is None:
+                    continue
+                sources.setdefault(loaded_source.path, loaded_source.source)
+                count += 1
+        return cls(_units(sources, roots))
+
+    @classmethod
+    def single(cls, path: Path, source: str) -> Self:
+        return cls(_units({path: source}))
+
+    def unit(self, path: Path) -> SourceUnit | None:
+        direct = self._units.get(path)
+        if direct is not None:
+            return direct
+        try:
+            return self._units.get(path.resolve())
+        except OSError:
+            return None
+
+    def nominal_for_field(self, name: str) -> SymbolRef | None:
+        matches = self._nominals.get(name)
+        return next(iter(matches)) if matches is not None and len(matches) == 1 else None
+
+    @staticmethod
+    def resolve(unit: SourceUnit, expression: ast.expr) -> SymbolRef | None:
+        if unit.module is None:
+            return None
+        if isinstance(expression, ast.Name):
+            return unit.imports.get(expression.id) or SymbolRef(unit.module, expression.id)
+        if isinstance(expression, ast.Attribute) and isinstance(expression.value, ast.Name):
+            root = unit.imports.get(expression.value.id)
+            if root is not None:
+                return SymbolRef(root.module, expression.attr) if not root.name else None
+        return None
+
+    def class_for(self, unit: SourceUnit, expression: ast.expr) -> ClassSummary | None:
+        symbol = self.resolve(unit, expression)
+        return self._classes.get(symbol) if symbol is not None else None
+
+    def annotation_contains_enum(self, unit: SourceUnit, annotation: ast.expr) -> bool:
+        for member in ast.walk(annotation):
+            if not isinstance(member, (ast.Name, ast.Attribute)):
+                continue
+            symbol = self.resolve(unit, member)
+            summary = self._classes.get(symbol) if symbol is not None else None
+            if summary is not None and summary.is_enum:
+                return True
+        return False
+
+    def source_unit(self, module: str) -> SourceUnit | None:
+        return self._by_module.get(module)
+
+
+def _units(sources: Mapping[Path, str], roots: Sequence[Path] = ()) -> dict[Path, SourceUnit]:
+    matched_classes = {
+        match.group(1)
+        for source in sources.values()
+        if "match " in source and "str(" in source
+        for match in _MATCH_CLASS_RE.finditer(source)
+    }
+    parsed: dict[Path, tuple[str | None, str, ast.Module | None]] = {}
+    for path, source in sources.items():
+        if not _is_index_candidate(source, matched_classes):
+            continue
+        tree: ast.Module | None = None
+        with suppress(SyntaxError):
+            tree = ast.parse(source, filename=str(path))
+        parsed[path] = (_module_name(path, roots), source, tree)
+    return {
+        path: SourceUnit(
+            path=path,
+            module=module,
+            source=source,
+            tree=tree,
+            imports=MappingProxyType(_imports(module, tree, is_package=path.name == "__init__.py")),
+        )
+        for path, (module, source, tree) in parsed.items()
+    }
+
+
+def _is_index_candidate(source: str, matched_classes: set[str]) -> bool:
+    return (
+        "NewType(" in source
+        or ("class " in source and any(marker in source for marker in ("Enum", "IntEnum", "StrEnum")))
+        or ("match " in source and "str(" in source)
+        or any(f"class {name}" in source for name in matched_classes)
+    )
+
+
+def _module_name(path: Path, roots: Sequence[Path]) -> str | None:
+    resolved = path.resolve()
+    root = next((candidate for candidate in roots if resolved == candidate or candidate in resolved.parents), None)
+    if root is not None:
+        package_dir: Path | None = None
+        for ancestor in resolved.parents:
+            if ancestor == root:
+                break
+            try:
+                if (ancestor / "__init__.py").is_file():
+                    package_dir = ancestor
+            except OSError:
+                return None
+        if package_dir is not None:
+            relative = resolved.relative_to(package_dir)
+            suffix = relative.parts[:-1] if relative.name == "__init__.py" else (*relative.parts[:-1], relative.stem)
+            return ".".join((package_dir.name, *suffix))
+    parts: list[str] = []
+    parent = path.parent
+    try:
+        while (parent / "__init__.py").is_file():
+            parts.append(parent.name)
+            parent = parent.parent
+    except OSError:
+        return None
+    if not parts:
+        if path.is_absolute():
+            return None
+        relative = [part for part in path.parts if part not in {".", ".."}]
+        if not relative:
+            return None
+        if path.name == "__init__.py":
+            return ".".join(relative[:-1]) or None
+        return ".".join([*relative[:-1], path.stem])
+    parts.reverse()
+    if path.name != "__init__.py":
+        parts.append(path.stem)
+    return ".".join(parts)
+
+
+def _project_roots(paths: Sequence[Path]) -> tuple[Path, ...]:
+    roots: list[Path] = []
+    for path in paths:
+        try:
+            resolved = path.resolve()
+        except OSError:
+            continue
+        if any(resolved == root or root in resolved.parents for root in roots):
+            continue
+        root = project_root(path)
+        if root is not None and root not in roots:
+            roots.append(root)
+        if len(roots) >= _MAX_ROOTS:
+            break
+    return tuple(sorted(roots))
+
+
+def _python_files(root: Path) -> Iterator[Path]:
+    for scanned, (directory, dir_names, file_names) in enumerate(os.walk(root), start=1):
+        if scanned > _MAX_DIRS_PER_ROOT:
+            return
+        parent = Path(directory)
+        dir_names[:] = [
+            name
+            for name in sorted(dir_names)
+            if not name.startswith(".") and name not in _SKIP_DIRS and not (parent / name / ".git").exists()
+        ]
+        for name in sorted(file_names):
+            if name.endswith(".py"):
+                yield parent / name
+
+
+def _imports(module: str | None, tree: ast.Module | None, *, is_package: bool) -> dict[str, SymbolRef]:
+    if module is None or tree is None:
+        return {}
+    result: dict[str, SymbolRef] = {}
+    package = module if is_package else module.rpartition(".")[0]
+    for node in tree.body:
+        if isinstance(node, ast.ImportFrom) and not any(alias.name == "*" for alias in node.names):
+            target = _relative_module(package, node.level, node.module)
+            if target is None:
+                continue
+            for alias in node.names:
+                result[alias.asname or alias.name] = SymbolRef(target, alias.name)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.asname:
+                    result[alias.asname] = SymbolRef(alias.name, "")
+    return result
+
+
+def _relative_module(package: str, level: int, module: str | None) -> str | None:
+    if level == 0:
+        return module
+    parts = package.split(".") if package else []
+    if level > len(parts) + 1:
+        return None
+    base = parts[: len(parts) - level + 1]
+    if module:
+        base.extend(module.split("."))
+    return ".".join(base) if base else None
+
+
+def _new_type(statement: ast.stmt, module: str) -> SymbolRef | None:
+    target: ast.Name | None = None
+    value: ast.expr | None = None
+    if isinstance(statement, ast.Assign) and len(statement.targets) == 1 and isinstance(statement.targets[0], ast.Name):
+        target, value = statement.targets[0], statement.value
+    elif isinstance(statement, ast.AnnAssign) and isinstance(statement.target, ast.Name):
+        target, value = statement.target, statement.value
+    if (
+        target is None
+        or not isinstance(value, ast.Call)
+        or _tail(value.func) != "NewType"
+        or len(value.args) < _NEW_TYPE_MIN_ARGS
+    ):
+        return None
+    declared = value.args[0]
+    carrier = value.args[1]
+    if not (
+        isinstance(declared, ast.Constant) and declared.value == target.id and _tail(carrier) in {"UUID", "int", "str"}
+    ):
+        return None
+    return SymbolRef(module, target.id)
+
+
+def _field_key(type_name: str) -> str:
+    first = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", type_name)
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", first).lower()
+
+
+def _tail(node: ast.expr) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""
+
+
+def _read_bounded_source(root: Path, path: Path) -> LoadedSource | None:
+    try:
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > _MAX_FILE_BYTES:
+            return None
+        resolved = path.resolve()
+        resolved.relative_to(root.resolve())
+        return LoadedSource(resolved, resolved.read_text(encoding="utf-8", errors="replace"))
+    except OSError, ValueError:
+        return None

{sarj_python_lint-0.71.0 → sarj_python_lint-0.72.0}/src/sarj_python_lint/rules/_registry.py

@@ -109,6 +109,8 @@ from sarj_python_lint.rules.prefer_walrus_comprehension_filter import (
 )
 from sarj_python_lint.rules.prefer_walrus_regex_match import PreferWalrusRegexMatch
 from sarj_python_lint.rules.prefer_walrus_stream_loop import PreferWalrusStreamLoop
+from sarj_python_lint.rules.preserve_declared_nominal_id import PreserveDeclaredNominalId
+from sarj_python_lint.rules.preserve_enum_types import PreserveEnumTypes
 from sarj_python_lint.rules.production_derived_test_cases import ProductionDerivedTestCases
 from sarj_python_lint.rules.pydantic_at_boundaries import PydanticAtBoundaries
 from sarj_python_lint.rules.redundant_class_docstring import RedundantClassDocstring
@@ -122,8 +124,13 @@ 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_ordinal_lower_bound import (
+    RequirePydanticOrdinalLowerBound,
+)
+from sarj_python_lint.rules.require_validated_row_factory import RequireValidatedRowFactory
 from sarj_python_lint.rules.restated_test_docstring import RestatedTestDocstring
 from sarj_python_lint.rules.source_coupled_test import SourceCoupledTest
+from sarj_python_lint.rules.sql_requires_injected_pool_owner import SqlRequiresInjectedPoolOwner
 from sarj_python_lint.rules.stepdown import Stepdown
 from sarj_python_lint.rules.store_insert_requires_on_conflict import (
     StoreInsertRequiresOnConflict,
@@ -220,6 +227,11 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         ProductionDerivedTestCases.id: ProductionDerivedTestCases,
         UncontrolledRandomnessInTest.id: UncontrolledRandomnessInTest,
         RepeatedStaticCallCases.id: RepeatedStaticCallCases,
+        RequireValidatedRowFactory.id: RequireValidatedRowFactory,
+        SqlRequiresInjectedPoolOwner.id: SqlRequiresInjectedPoolOwner,
+        PreserveDeclaredNominalId.id: PreserveDeclaredNominalId,
+        PreserveEnumTypes.id: PreserveEnumTypes,
+        RequirePydanticOrdinalLowerBound.id: RequirePydanticOrdinalLowerBound,
     }
 )
 

sarj_python_lint-0.72.0/src/sarj_python_lint/rules/preserve_declared_nominal_id.py

@@ -0,0 +1,143 @@
+"""SARJ416 preserves project-declared nominal identifier roles.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_preserve_declared_nominal_id.py
+"""
+
+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,
+    ProjectRule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    parse_or_none,
+)
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+from sarj_python_lint.rules._project_index import ProjectIndexSet
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@final
+class PreserveDeclaredNominalId(ProjectRule):
+    id = "preserve-declared-nominal-id"
+    code = "SARJ416"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Keep project-declared nominal identifier types in test overrides.",
+        rationale="A fake override that widens a declared ID role back to its primitive carrier defeats type-checker swap protection.",
+        remediation="Import and propagate the matching project `NewType` instead of annotating the role with its carrier.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "The field name must map exactly and unambiguously to a first-party NewType declaration.",
+            "Only explicit override methods in test files are inspected; production boundary discovery remains SARJ093's responsibility.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="declared-id-erased",
+                title="A declared nominal ID is widened to string",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/fake.py",
+                        "from typing import NewType, override\nSipTrunkId = NewType('SipTrunkId', str)\nclass Fake:\n    @override\n    def route(self, sip_trunk_id: str): ...\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/fake.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="declared-id-preserved",
+                title="A declared nominal ID remains nominal",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/fake.py",
+                        "from typing import NewType, override\nSipTrunkId = NewType('SipTrunkId', str)\nclass Fake:\n    @override\n    def route(self, sip_trunk_id: SipTrunkId): ...\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/fake.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if (
+            ("@override" not in source and ".override" not in source)
+            or is_generated(path, source)
+            or not is_test_path(path)
+            or "migrations" in {part.lower() for part in path.parts}
+        ):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        indexes = self._project_indexes or ProjectIndexSet.single(path, source)
+        diagnostics: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                if not any(_tail(item) == "override" for item in node.decorator_list):
+                    continue
+                for argument in [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]:
+                    diagnostics.extend(_diagnose(path, argument.arg, argument.annotation, indexes, self.code))
+        return sorted(diagnostics, key=lambda item: (item.line, item.col))
+
+
+def _diagnose(
+    path: Path,
+    name: str,
+    annotation: ast.expr | None,
+    indexes: ProjectIndexSet,
+    code: str,
+) -> list[Diagnostic]:
+    nominal = indexes.nominal_for_field(name)
+    if nominal is None or annotation is None or not _raw_primitive(annotation):
+        return []
+    return [
+        Diagnostic(
+            path=path,
+            line=annotation.lineno,
+            col=annotation.col_offset + 1,
+            code=code,
+            severity=Severity.WARNING,
+            message=f"`{name}` erases declared nominal `{nominal.name}`; propagate the nominal ID type through this boundary",
+        )
+    ]
+
+
+def _raw_primitive(node: ast.expr | None) -> bool:
+    match node:
+        case ast.Name(id=name):
+            return name in {"UUID", "int", "str"}
+        case ast.BinOp(left=left, op=ast.BitOr(), right=right):
+            return _raw_primitive(left) or _raw_primitive(right)
+        case ast.Subscript(slice=member):
+            return _raw_primitive(member)
+        case ast.Tuple(elts=members):
+            return any(_raw_primitive(item) for item in members)
+        case _:
+            return False
+
+
+def _tail(node: ast.expr) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""