sarj-python-lint 1.2.0__tar.gz → 1.2.4__tar.gz

{sarj_python_lint-1.2.0 → sarj_python_lint-1.2.4}/PKG-INFO

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

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

{sarj_python_lint-1.2.0 → sarj_python_lint-1.2.4}/src/sarj_python_lint/_analysis_session.py

@@ -4,6 +4,7 @@ from typing import TYPE_CHECKING, final
 
 from sarj_python_lint._python_target import PythonTargetFacts
 from sarj_python_lint.rules._first_party import FirstPartyFacts
+from sarj_python_lint.rules._nominal_project import NominalProjectFacts
 
 
 if TYPE_CHECKING:
@@ -16,3 +17,4 @@ class AnalysisSession:
         self.project: ProjectIndexSet | None = None
         self.first_party = FirstPartyFacts()
         self.python_target = PythonTargetFacts()
+        self.nominal_project = NominalProjectFacts()

sarj_python_lint-1.2.4/src/sarj_python_lint/rules/_nominal_project.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+import tomllib
+from types import MappingProxyType
+from typing import TYPE_CHECKING, TypeGuard, final
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+from sarj_python_lint.rules._first_party import distribution_root
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint.rules._first_party import FirstPartyFacts
+
+
+_MAX_FILES = 5_000
+_MAX_DIRECTORIES = 3_000
+_MAX_BYTES = 500_000
+_MAX_TOTAL_BYTES = 25_000_000
+_SKIP = frozenset({"node_modules", "vendor", "vendored", "build", "dist", "__pycache__", "venv"})
+
+
+@dataclass(frozen=True)
+class NominalSource:
+    path: Path
+    text: str
+
+    @cached_property
+    def tree(self) -> ast.Module | None:
+        try:
+            tree = ast.parse(self.text, filename=str(self.path))
+        except SyntaxError:
+            return None
+        if any(
+            isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names)
+            for node in ast.walk(tree)
+        ):
+            return None
+        return tree
+
+    @cached_property
+    def imports(self) -> ImportIndex:
+        tree = self.tree
+        if tree is None:
+            return ImportIndex(MappingProxyType({}), frozenset())
+        imports = ImportIndex.from_tree(tree)
+        mutated = {
+            ast.unparse(node).partition(".")[0]
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Attribute) and isinstance(node.ctx, (ast.Store, ast.Del))
+        }
+        return ImportIndex(
+            MappingProxyType({name: target for name, target in imports.bindings.items() if name not in mutated}),
+            imports.shadowed_names | mutated,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _Workspace:
+    root: Path
+    members: tuple[str, ...]
+    excludes: tuple[str, ...]
+
+    def contains(self, path: Path) -> bool:
+        if path == self.root:
+            return True
+        if not path.is_relative_to(self.root):
+            return False
+        relative = path.relative_to(self.root)
+        return any(relative.full_match(pattern) for pattern in self.members) and not any(
+            relative.full_match(pattern) for pattern in self.excludes
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _Distribution:
+    root: Path
+    name: str | None
+    dependencies: frozenset[str]
+    workspace: _Workspace | None
+
+
+@final
+class NominalProjectFacts:
+    # One request owns these caches; subsequent requests see source changes.
+    def __init__(self) -> None:
+        self._distributions: dict[Path, tuple[_Distribution, ...]] = {}
+        self._sources: dict[Path, dict[str, NominalSource]] = {}
+        self._scopes: dict[Path, dict[str, NominalSource]] = {}
+
+    def sources(self, path: Path, first_party: FirstPartyFacts) -> dict[str, NominalSource]:
+        owner = distribution_root(path, facts=first_party)
+        root = first_party.project_root(path)
+        if owner is None or root is None:
+            return {}
+        if owner in self._scopes:
+            return self._scopes[owner]
+        distributions = self._accessible_distributions(owner, root)
+        sources = self._merge_sources(distributions)
+        self._scopes[owner] = sources
+        return sources
+
+    def _accessible_distributions(self, owner: Path, root: Path) -> tuple[_Distribution, ...]:
+        if root not in self._distributions:
+            self._distributions[root] = tuple(
+                distribution
+                for manifest in _files(root, "pyproject.toml")
+                if (distribution := _distribution(manifest)) is not None
+            )
+        distributions = self._distributions[root]
+        own = next(
+            (
+                distribution
+                for distribution in distributions
+                if distribution.root == owner and distribution.name is not None
+            ),
+            None,
+        )
+        if own is None:
+            return ()
+        distributions = _workspace_distributions(distributions, owner)
+        return tuple(
+            distribution
+            for distribution in distributions
+            if distribution == own
+            or (
+                distribution.name in own.dependencies
+                and sum(candidate.name == distribution.name for candidate in distributions) == 1
+            )
+        )
+
+    def _merge_sources(self, distributions: tuple[_Distribution, ...]) -> dict[str, NominalSource]:
+        sources: dict[str, NominalSource] = {}
+        ambiguous: set[str] = set()
+        for distribution in distributions:
+            if distribution.root not in self._sources:
+                self._sources[distribution.root] = _sources(distribution.root)
+            for module, source in self._sources[distribution.root].items():
+                if module in sources:
+                    ambiguous.add(module)
+                sources[module] = source
+        return {module: source for module, source in sources.items() if module not in ambiguous}
+
+
+def _workspace_distributions(distributions: tuple[_Distribution, ...], owner: Path) -> tuple[_Distribution, ...]:
+    workspaces = [
+        distribution.workspace
+        for distribution in distributions
+        if distribution.workspace is not None and distribution.workspace.contains(owner)
+    ]
+    if workspaces:
+        workspace = max(workspaces, key=lambda scope: len(scope.root.parts))
+        distributions = tuple(distribution for distribution in distributions if workspace.contains(distribution.root))
+    return distributions
+
+
+def _distribution(manifest: Path) -> _Distribution | None:
+    try:
+        if manifest.is_symlink() or manifest.stat().st_size > _MAX_BYTES:
+            return None
+        document: object = tomllib.loads(manifest.read_text(encoding="utf-8"))
+    except OSError, ValueError:
+        return None
+    if not _is_mapping(document):
+        return None
+    workspace = _workspace(manifest.parent, document)
+    project = document.get("project")
+    if not _is_mapping(project):
+        return _Distribution(manifest.parent, None, frozenset(), workspace) if workspace is not None else None
+    name = project.get("name")
+    dependencies = project.get("dependencies", [])
+    if not isinstance(name, str) or not _is_list(dependencies):
+        return None
+    names: set[str] = set()
+    for dependency in dependencies:
+        if not isinstance(dependency, str):
+            continue
+        try:
+            names.add(canonicalize_name(Requirement(dependency).name))
+        except InvalidRequirement:
+            continue
+    return _Distribution(manifest.parent, canonicalize_name(name), frozenset(names), workspace)
+
+
+def _workspace(root: Path, document: dict[object, object]) -> _Workspace | None:
+    value: object = document
+    for key in ("tool", "uv", "workspace"):
+        if not _is_mapping(value):
+            return None
+        value = value.get(key)
+    if not _is_mapping(value):
+        return None
+    members = _patterns(value.get("members"))
+    excludes = _patterns(value.get("exclude", []))
+    if members is None or excludes is None:
+        return None
+    return _Workspace(root, members, excludes)
+
+
+def _patterns(value: object) -> tuple[str, ...] | None:
+    if not _is_list(value) or any(not isinstance(item, str) for item in value):
+        return None
+    return tuple(item for item in value if isinstance(item, str))
+
+
+def _files(root: Path, pattern: str) -> list[Path]:
+    found: list[Path] = []
+    try:
+        for count, (directory, directories, filenames) in enumerate(root.walk()):
+            if count >= _MAX_DIRECTORIES or len(found) >= _MAX_FILES:
+                # A partial inventory cannot establish uniqueness.
+                return []
+            directories[:] = sorted(name for name in directories if not name.startswith(".") and name not in _SKIP)
+            found.extend(directory / name for name in sorted(filenames) if Path(name).match(pattern))
+            if len(found) > _MAX_FILES:
+                return []
+    except OSError:
+        return []
+    return found
+
+
+def _sources(root: Path) -> dict[str, NominalSource]:
+    sources: dict[str, NominalSource] = {}
+    ambiguous: set[str] = set()
+    total_bytes = 0
+    for path in _files(root, "*.py"):
+        try:
+            total_bytes += path.stat().st_size
+        except OSError:
+            continue
+        if total_bytes > _MAX_TOTAL_BYTES:
+            return {}
+        module = _module_name(root, path)
+        if not module:
+            continue
+        source = _source(path)
+        if source is None:
+            continue
+        if module in sources:
+            ambiguous.add(module)
+        sources[module] = source
+    return {module: source for module, source in sources.items() if module not in ambiguous}
+
+
+def _module_name(root: Path, path: Path) -> str | None:
+    # A nested manifest owns its sources even when it uses the same namespace.
+    if any(
+        (parent / "pyproject.toml").is_file() for parent in path.parents if parent != root and root in parent.parents
+    ):
+        return None
+    relative = path.relative_to(root)
+    parts = relative.parts[1:] if relative.parts[0] == "src" else relative.parts
+    return ".".join(parts[:-1] if parts[-1] == "__init__.py" else (*parts[:-1], path.stem)) or None
+
+
+def _source(path: Path) -> NominalSource | None:
+    try:
+        if path.is_symlink() or path.stat().st_size > _MAX_BYTES:
+            return None
+        text = path.read_text(encoding="utf-8")
+        if is_generated(path, text):
+            return None
+    except OSError, UnicodeError:
+        return None
+    return NominalSource(path, text)
+
+
+def _is_mapping(value: object) -> TypeGuard[dict[object, object]]:
+    return isinstance(value, dict)
+
+
+def _is_list(value: object) -> TypeGuard[list[object]]:
+    return isinstance(value, list)

{sarj_python_lint-1.2.0 → sarj_python_lint-1.2.4}/src/sarj_python_lint/rules/no_unused_value_marker.py

@@ -16,12 +16,9 @@ from sarj_python_lint.rule_base import (
     Severity,
     is_suppressed,
 )
-from sarj_python_lint.rules._ast_index import walk as walk_ast
 
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
-
     from sarj_python_lint._file_context import PythonFileContext
 
 
@@ -34,27 +31,28 @@ class NoUnusedValueMarker(Rule):
         summary="Do not use standalone assignments to `_` to discard values.",
         rationale=(
             "A standalone `_ = value` assignment adds a binding without clarifying intent. A side-effecting call can "
-            "be invoked directly. Pure references to formal parameters are excluded because callback and protocol "
-            "signatures may require names that Ruff otherwise reports as unused."
+            "be invoked directly. Reading unused parameters only to satisfy a linter hides whether a callback is "
+            "intentionally inert or implements an incomplete contract."
         ),
         remediation=(
             "Invoke calls directly instead of assigning their result to `_`. Remove or rename locally owned unused "
             "values; when an external interface requires the exact unused parameter, put a narrow reasoned linter "
-            "suppression on its declaration."
+            "suppression on its declaration. Use an explicit empty body for an intentional stub, `@override` for "
+            "a real override, or `NotImplementedError` for an unsupported operation; preserve required keyword names."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Plain and annotated assignments whose standalone target is `_` are reported, including chained assignments.",
-            "Pure name or tuple references to the enclosing function's unchanged parameters are excluded.",
+            "Formal-parameter references are reported too, including positional, keyword-only, and variadic parameters.",
             "Unpacking placeholders, loop targets, wildcard imports, and underscore-prefixed names are excluded.",
             "Generated and vendored files are excluded.",
         ),
         examples=(
             RuleExample(
                 example_id="callback-parameter-marker",
-                title="A callback keeps its required parameter names",
-                outcome=ExampleOutcome.NO_MATCH,
+                title="A callback disguises unused parameters with a discard binding",
+                outcome=ExampleOutcome.MATCH,
                 files=(
                     ExampleFile.python(
                         "app/adapter.py",
@@ -62,8 +60,24 @@ class NoUnusedValueMarker(Rule):
                     ),
                 ),
                 focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=1,
+                public=True,
+                scenario="callback-parameters",
+            ),
+            RuleExample(
+                example_id="intentional-callback-stub",
+                title="An intentional stub preserves its callback signature",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/adapter.py",
+                        "def on(event: str, callback: object) -> None:\n    pass\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/adapter.py"),
                 expected_count=0,
-                public=False,
+                public=True,
+                scenario="callback-parameters",
             ),
             RuleExample(
                 example_id="discarded-nonparameter-value",
@@ -138,11 +152,6 @@ class NoUnusedValueMarker(Rule):
         ]
         if not markers:
             return []
-        parents: Mapping[ast.AST, ast.AST] = (
-            context.parents
-            if any(isinstance(node, ast.Assign) and isinstance(node.value, (ast.Name, ast.Tuple)) for node in markers)
-            else {}
-        )
         return [
             Diagnostic(
                 path=path,
@@ -156,7 +165,7 @@ class NoUnusedValueMarker(Rule):
                 ),
             )
             for node in markers
-            if not _is_pure_parameter_marker(node, parents) and not is_suppressed(source_lines, node.lineno, self.code)
+            if not is_suppressed(source_lines, node.lineno, self.code)
         ]
 
 
@@ -164,42 +173,3 @@ def _is_unused_value_marker(node: ast.Assign | ast.AnnAssign) -> bool:
     if isinstance(node, ast.AnnAssign):
         return node.value is not None and isinstance(node.target, ast.Name) and node.target.id == "_"
     return any(isinstance(target, ast.Name) and target.id == "_" for target in node.targets)
-
-
-def _is_pure_parameter_marker(
-    node: ast.Assign | ast.AnnAssign,
-    parents: Mapping[ast.AST, ast.AST],
-) -> bool:
-    if not isinstance(node, ast.Assign) or len(node.targets) != 1:
-        return False
-    if not isinstance(node.targets[0], ast.Name) or node.targets[0].id != "_":
-        return False
-    names = _marker_reference_names(node.value)
-    if names is None:
-        return False
-    function = _enclosing_function(node, parents)
-    if function is None:
-        return False
-    parameters = {argument.arg for argument in walk_ast(function.args) if isinstance(argument, ast.arg)}
-    return names <= parameters and not any(
-        isinstance(child, ast.Name) and isinstance(child.ctx, ast.Store) and child.id in names
-        for child in walk_ast(function)
-    )
-
-
-def _marker_reference_names(value: ast.expr) -> set[str] | None:
-    values = value.elts if isinstance(value, ast.Tuple) else [value]
-    if not values or not all(isinstance(item, ast.Name) for item in values):
-        return None
-    return {item.id for item in values if isinstance(item, ast.Name)}
-
-
-def _enclosing_function(
-    node: ast.AST, parents: Mapping[ast.AST, ast.AST]
-) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
-    current = node
-    while current in parents:
-        current = parents[current]
-        if isinstance(current, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            return current
-    return None

{sarj_python_lint-1.2.0 → sarj_python_lint-1.2.4}/src/sarj_python_lint/rules/prefer_match_assert_never.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import ast
 from pathlib import PurePosixPath
+import re
 from typing import TYPE_CHECKING, NamedTuple, final, override
 
 from sarj_python_lint.rule_base import (
@@ -14,8 +15,10 @@ from sarj_python_lint.rule_base import (
     RuleDocumentation,
     RuleExample,
     Severity,
+    is_suppressed,
 )
 from sarj_python_lint.rules._ast_index import nodes
+from sarj_python_lint.rules._suppression_comments import scan_comments_or_none
 
 
 if TYPE_CHECKING:
@@ -28,6 +31,8 @@ if TYPE_CHECKING:
 _MIN_ARMS = 2
 
 _ENUM_BASES = frozenset({"Enum", "StrEnum", "IntEnum", "ReprEnum"})
+_ARGUMENT_IGNORE = re.compile(r"^(?:type|pyright):\s*ignore\b(?:\[([^\]]*)\])?")
+_TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
 
 
 class _EnumComparison(NamedTuple):
@@ -58,17 +63,20 @@ class PreferMatchAssertNever(Rule):
     documentation = RuleDocumentation(
         summary="Typed enum dispatch must not silently ignore unhandled members.",
         rationale=(
-            "A no-op wildcard or else branch hides missing enum members and lets newly added members pass unnoticed."
+            "A no-op wildcard or else branch hides missing enum members and lets newly added members pass unnoticed. "
+            "Suppressing the argument-type error at assert_never also disables its static exhaustiveness guarantee."
         ),
         remediation=(
             "Handle every enum member, bind the catch-all value, and pass it to `typing.assert_never`; "
-            "raise an explicit exception when static exhaustiveness is unavailable."
+            "raise an explicit exception when static exhaustiveness is unavailable. Narrow the accepted type or "
+            "handle missing variants instead of suppressing assert_never's argument check."
         ),
         category=RuleCategory.CORRECTNESS,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only subjects explicitly annotated as a locally declared Enum, StrEnum, IntEnum, or ReprEnum are checked.",
             "Flags, imported or untyped domains, class-pattern unions, guarded arms, generated files, and dynamic dispatch are excluded.",
+            "Independently warns on import-proven assert_never calls with a trailing blanket or argument-type ignore; module-wide disables are not analyzed.",
         ),
         examples=(
             RuleExample(
@@ -115,7 +123,7 @@ class PreferMatchAssertNever(Rule):
         imports = context.imports
         local_enums = _local_enum_names(module_classdefs, imports, tree)
         enum_members = _enum_members(module_classdefs, local_enums)
-        diags: list[Diagnostic] = []
+        diags = _suppressed_exhaustiveness_calls(context, self.code)
         consumed_elifs: set[int] = set()
         for node in context.nodes(ast.Match, ast.If):
             if isinstance(node, ast.Match):
@@ -157,6 +165,48 @@ class PreferMatchAssertNever(Rule):
         return diags
 
 
+def _suppressed_exhaustiveness_calls(context: PythonFileContext, code: str) -> list[Diagnostic]:
+    if "ignore" not in context.source:
+        return []
+    comments = scan_comments_or_none(context.source)
+    if comments is None:
+        return []
+    ignored_lines = {
+        comment.line for comment in comments if not comment.standalone and _ignores_argument_type(comment.body)
+    }
+    findings: list[Diagnostic] = []
+    for call in context.nodes(ast.Call):
+        if not context.imports.resolves(call.func, sources=_TYPING_SOURCES, symbol="assert_never"):
+            continue
+        call_lines = range(call.lineno, (call.end_lineno or call.lineno) + 1)
+        if not any(line in ignored_lines for line in call_lines):
+            continue
+        if any(is_suppressed(context.source_lines, line, code) for line in call_lines):
+            continue
+        findings.append(
+            Diagnostic(
+                path=context.path,
+                line=call.lineno,
+                col=call.col_offset + 1,
+                code=code,
+                severity=Severity.WARNING,
+                message=(
+                    "assert_never has its argument-type check suppressed; handle the missing variants, narrow "
+                    "the accepted type, or use an explicit runtime exception instead of claiming exhaustiveness."
+                ),
+            )
+        )
+    return findings
+
+
+def _ignores_argument_type(comment: str) -> bool:
+    match = _ARGUMENT_IGNORE.match(comment)
+    if match is None:
+        return False
+    codes = match.group(1)
+    return codes is None or bool({code.strip() for code in codes.split(",")} & {"reportArgumentType", "arg-type"})
+
+
 def _module_scope_classdefs(tree: ast.Module) -> list[ast.ClassDef]:
     return [stmt for stmt in tree.body if isinstance(stmt, ast.ClassDef)]