sarj-python-lint 1.75.0__tar.gz → 1.77.0__tar.gz

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.75.0
+Version: 1.77.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/
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
 Requires-Dist: ruff>=0.17.2
-Requires-Dist: sarj-rule-contracts==0.4.0
+Requires-Dist: sarj-rule-contracts==0.4.1
 Requires-Dist: sqlglot==30.24.0
 Requires-Dist: typer==0.27.3
 Description-Content-Type: text/markdown

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.75.0"
+version = "1.77.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["sarj-rule-contracts==0.4.0", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
+dependencies = ["sarj-rule-contracts==0.4.1", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/src/sarj_python_lint/__main__.py

@@ -9,8 +9,9 @@ import json
 from pathlib import Path
 import sys
 from types import MappingProxyType
-from typing import Annotated, NamedTuple
+from typing import TYPE_CHECKING, Annotated, NamedTuple
 
+from sarj_rule_contracts import RuleId
 import typer
 
 from sarj_python_lint import __version__
@@ -26,6 +27,10 @@ from sarj_python_lint.rules._project_index import ProjectIndexSet
 from sarj_python_lint.suppression_policy import PROTECTED_SUPPRESSION_CODES
 
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
 SKIP_DIR_NAMES = frozenset(
     {
         "node_modules",
@@ -86,18 +91,18 @@ def _python_files(p: Path) -> list[Path]:
     return sorted(out)
 
 
-def _canonical_rule_ids(rule_ids: list[str]) -> list[str]:
+def _canonical_rule_ids(rule_names: Sequence[str]) -> list[RuleId]:
     aliases = {
         alias: rule_id
         for rule_id, cls in REGISTRY.items()
         if (documentation := cls.documentation) is not None
         for alias in documentation.aliases
     }
-    return list(dict.fromkeys(rid if rid in REGISTRY else aliases.get(rid, rid) for rid in rule_ids))
+    return list(dict.fromkeys(RuleId(name if name in REGISTRY else aliases.get(name, name)) for name in rule_names))
 
 
-def _check(rule_ids: list[str], paths: list[Path], *, jobs: int = 1) -> list[Diagnostic]:
-    rule_ids = _canonical_rule_ids(rule_ids)
+def _check(rule_names: Sequence[str], paths: list[Path], *, jobs: int = 1) -> list[Diagnostic]:
+    rule_ids = _canonical_rule_ids(rule_names)
     unknown = [rid for rid in rule_ids if rid not in REGISTRY]
     if unknown:
         sys.stderr.write(f"unknown rule(s): {', '.join(unknown)}\n")
@@ -145,7 +150,7 @@ def check_source(
 
 
 def analyze(
-    rule_ids: list[str],
+    rule_ids: Sequence[str],  # sarj-noqa: SARJ093 -- Public parsing boundary accepts raw names.
     paths: list[Path],
     *,
     baseline: Path | None = None,

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/src/sarj_python_lint/benchmark.py

@@ -8,14 +8,19 @@ from pathlib import Path
 from statistics import median
 import sys
 from time import perf_counter
-from typing import Annotated
+from typing import TYPE_CHECKING, Annotated
 
+from sarj_rule_contracts import RuleId
 import typer
 
 from sarj_python_lint.__main__ import analyze, expand_paths
 from sarj_python_lint.rules import REGISTRY
 
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
 @dataclass(frozen=True, slots=True)
 class BenchmarkSample:
     seconds: float
@@ -43,11 +48,16 @@ def peak_memory_bytes() -> int | None:
     return peak if sys.platform == "darwin" else peak * 1024
 
 
-def measure(paths: list[Path], rule_ids: list[str] | None = None, *, repeats: int = 5) -> BenchmarkReport:
+def measure(
+    paths: list[Path],
+    rule_ids: Sequence[str] | None = None,  # sarj-noqa: SARJ093 -- Public input accepts raw rule names.
+    *,
+    repeats: int = 5,
+) -> BenchmarkReport:
     if repeats < 1:
         msg = "repeats must be positive"
         raise ValueError(msg)
-    selected = sorted(REGISTRY) if rule_ids is None else sorted(rule_ids)
+    selected = [RuleId(name) for name in sorted(REGISTRY if rule_ids is None else rule_ids)]
     unknown = sorted(set(selected) - REGISTRY.keys())
     if unknown:
         msg = f"unknown rule(s): {', '.join(unknown)}"

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/src/sarj_python_lint/rules/_fastapi.py

@@ -32,6 +32,7 @@ RESPONSE_TYPES = frozenset(
     }
 )
 _DEPENDENCY_MARKERS = frozenset({"Depends", "Security"})
+_CONSTRUCTOR_SOURCES = frozenset({"fastapi", "fastapi.applications", "fastapi.routing"})
 _MAX_IMPORTED_MODULE_BYTES = 500_000
 _MAX_IMPORT_HOPS = 8
 _MAX_PATH_ANCESTORS = 32
@@ -134,6 +135,7 @@ class FastapiIndex:
         self._node_classes: dict[int, int | None] = {}
         self._route_scopes: dict[int, int] = {}
         self._scope_parents: dict[int, int | None] = {0: None}
+        self._class_scopes: set[int] = set()
         self._index_scopes(tree)
         self._read_imports(tree)
         self._read_aliases(tree)
@@ -145,6 +147,7 @@ class FastapiIndex:
             self._node_scopes[id(node)] = scope
             if isinstance(node, ast.ClassDef):
                 class_owner = node.lineno
+                self._class_scopes.add(node.lineno)
                 self._scope_parents[node.lineno] = scope
                 scope = node.lineno
             self._node_classes[id(node)] = class_owner
@@ -272,7 +275,7 @@ class FastapiIndex:
 
     def _resolve_alias(self, key: _ReceiverKey, value: ast.expr) -> bool:
         source = self._receiver_key(key.scope, _binding_name(value))
-        constructor_kind = self._constructor_kind(value)
+        constructor_kind = self.constructor_kind(value)
         if constructor_kind is not None:
             self._register_constructor(key, value, constructor_kind)
             return True
@@ -337,25 +340,26 @@ class FastapiIndex:
         return isinstance(value, ast.Constant) and value.value is False
 
     def _is_constructor_call(self, node: ast.expr) -> bool:
-        return self._constructor_kind(node) is not None
+        return self.constructor_kind(node) is not None
 
-    def _constructor_kind(self, node: ast.expr) -> Literal["FastAPI", "APIRouter"] | None:
+    def constructor_kind(self, node: ast.expr) -> Literal["FastAPI", "APIRouter"] | None:
         if not isinstance(node, ast.Call):
             return None
-        if isinstance(node.func, ast.Name):
-            canonical = self.symbols.get(node.func.id)
-            if canonical == "FastAPI":
-                return "FastAPI"
-            if canonical == "APIRouter":
-                return "APIRouter"
-            return None
-        if (
-            isinstance(node.func, ast.Attribute)
-            and isinstance(node.func.value, ast.Name)
-            and node.func.value.id in self.modules
-            and node.func.attr in {"FastAPI", "APIRouter"}
-        ):
-            return "FastAPI" if node.func.attr == "FastAPI" else "APIRouter"
+        root = self._root_name(node.func) if isinstance(node.func, ast.Attribute) else flat_name(node.func)
+        local_scope = self._node_scopes.get(id(node), 0)
+        scope: int | None = local_scope
+        while scope is not None and scope != 0:
+            # Method bodies do not close over their class namespace.
+            if (scope == local_scope or scope not in self._class_scopes) and _ReceiverKey(
+                scope, root
+            ) in self.bound_names:
+                return None
+            scope = self._scope_parents[scope]
+        canonical = self.imports.resolved_symbol(node.func, sources=_CONSTRUCTOR_SOURCES)
+        if canonical == "FastAPI":
+            return "FastAPI"
+        if canonical == "APIRouter":
+            return "APIRouter"
         return None
 
     def routes(self, function: ast.FunctionDef | ast.AsyncFunctionDef) -> tuple[Route, ...]:

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/src/sarj_python_lint/rules/_registry.py

@@ -240,6 +240,7 @@ from sarj_python_lint.rules.no_work_verb_get_route import NoWorkVerbGetRoute
 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_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
@@ -255,6 +256,7 @@ from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOr
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        PreferGroupedSettings.id: PreferGroupedSettings,
         NoRedundantLocalAlias.id: NoRedundantLocalAlias,
         PytestFixtureReturnsClosedResource.id: PytestFixtureReturnsClosedResource,
         DuplicatePytestFixtureParams.id: DuplicatePytestFixtureParams,

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/src/sarj_python_lint/rules/fastapi_class_router_contract.py

@@ -42,19 +42,21 @@ 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.",
+        summary="FastAPI HTTP routes 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."
+            "`response_model=NamedResponse` with a matching named return annotation. Compose the application with "
+            "`FastAPI.include_router(...)` instead of declaring HTTP handlers directly on it."
         ),
         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.",
+            "Tests, generated code, and hidden routes are excluded. FastAPI application construction and include_router composition are allowed.",
+            "Response-model checks exclude 204/304 responses and explicit stream/file/HTML/text/redirect responses.",
         ),
         examples=(
             RuleExample(
@@ -66,6 +68,38 @@ class FastapiClassRouterContract(Rule):
                 expected_count=1,
                 public=True,
             ),
+            RuleExample(
+                example_id="direct-app-route",
+                title="An application declares an HTTP handler directly",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/routes.py",
+                        "from fastapi import FastAPI\napp = FastAPI()\n"
+                        "@app.get('/items', response_model=ItemsResponse)\n"
+                        "def items() -> ItemsResponse:\n    return ItemsResponse(items=[])\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/routes.py"),
+                expected_count=1,
+                public=True,
+                scenario="application-composition",
+            ),
+            RuleExample(
+                example_id="app-router-composition",
+                title="An application includes a class-owned router",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/routes.py",
+                        "from fastapi import FastAPI\napp = FastAPI()\napp.include_router(ItemRouter(service).build())\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/routes.py"),
+                expected_count=0,
+                public=True,
+                scenario="application-composition",
+            ),
             RuleExample(
                 example_id="class-router",
                 title="A class builds and returns its router",
@@ -99,6 +133,7 @@ class FastapiClassRouterContract(Rule):
             node for node in context.nodes(ast.AST) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
         ):
             routes = tuple(route for route in index.routes(function) if not route.is_hidden)
+            findings.extend(_direct_app_route_findings(path, routes))
             for route in routes:
                 problem = _response_problem(function, route, index)
                 if problem is not None:
@@ -106,6 +141,20 @@ class FastapiClassRouterContract(Rule):
         return sorted(findings, key=lambda finding: (finding.line, finding.col, finding.message))
 
 
+def _direct_app_route_findings(path: Path, routes: tuple[Route, ...]) -> list[Diagnostic]:
+    decorators = {route.decorator for route in routes if route.receiver_kind == "FastAPI"}
+    return [
+        Diagnostic(
+            path,
+            decorator.lineno,
+            decorator.col_offset + 1,
+            FastapiClassRouterContract.code,
+            "declare HTTP routes on a local APIRouter returned by `*Router.build()`, then compose with include_router",
+        )
+        for decorator in decorators
+    ]
+
+
 def _router_construction_findings(
     path: Path,
     tree: ast.Module,
@@ -116,7 +165,7 @@ def _router_construction_findings(
 ) -> list[Diagnostic]:
     findings: list[Diagnostic] = []
     for call in (node for node in walk_ast(tree, index=node_index) if isinstance(node, ast.Call)):
-        if index.canonical(call.func) != "APIRouter":
+        if index.constructor_kind(call) != "APIRouter":
             continue
         function = _ancestor(call, parents, (ast.FunctionDef, ast.AsyncFunctionDef))
         cls = _ancestor(call, parents, ast.ClassDef)

{sarj_python_lint-1.75.0 → sarj_python_lint-1.77.0}/src/sarj_python_lint/rules/fastapi_explicit_openapi_contract.py

@@ -30,6 +30,8 @@ from sarj_python_lint.rules._paths import is_test_path
 
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping
+
     from sarj_python_lint._file_context import PythonFileContext
 
 
@@ -87,6 +89,7 @@ class FastapiExplicitOpenapiContract(Rule):
         limitations=(
             "Hidden routes, WebSocket handlers, tests, generated files, documentation-source examples, and unrelated decorators are excluded.",
             "Dynamic response mappings are accepted when their contents cannot be resolved statically.",
+            "Operation ID conflicts require unconditional registrations with literal IDs and paths on the same local router; conditional registrations, dynamic IDs, OpenAPI overrides, and cross-router composition require generated-schema validation.",
             "Explicit status and parameter-location findings are organizational policy even when FastAPI inference would generate valid OpenAPI.",
             (
                 "Fixed-record return inference is local and conservative: dynamic keys, opaque escapes, and ambiguous "
@@ -193,6 +196,44 @@ class FastapiExplicitOpenapiContract(Rule):
                 scenario="unannotated-record",
                 public=True,
             ),
+            RuleExample(
+                example_id="duplicate-operation-id",
+                title="Two operations reuse one client method identifier",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "api.py",
+                        "from fastapi import APIRouter\n\nrouter = APIRouter()\n\n"
+                        "@router.get('/items', status_code=200, operation_id='items')\n"
+                        "async def read_items() -> ItemsResponse: ...\n\n"
+                        "@router.post('/items', status_code=201, operation_id='items')\n"
+                        "async def create_item() -> ItemResponse: ...\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("api.py"),
+                expected_count=1,
+                scenario="operation-id",
+                public=True,
+            ),
+            RuleExample(
+                example_id="unique-operation-ids",
+                title="Each operation has a distinct client method identifier",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "api.py",
+                        "from fastapi import APIRouter\n\nrouter = APIRouter()\n\n"
+                        "@router.get('/items', status_code=200, operation_id='read_items')\n"
+                        "async def read_items() -> ItemsResponse: ...\n\n"
+                        "@router.post('/items', status_code=201, operation_id='create_item')\n"
+                        "async def create_item() -> ItemResponse: ...\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("api.py"),
+                expected_count=0,
+                scenario="operation-id",
+                public=True,
+            ),
         ),
     )
     description: str = documentation.summary
@@ -228,6 +269,7 @@ class FastapiExplicitOpenapiContract(Rule):
                 findings.extend(_check_projection(route))
                 findings.extend(_check_response_statuses(route, index))
         findings.extend(_check_route_conflicts(declared))
+        findings.extend(_check_operation_ids(declared, context.parents))
         return [
             Diagnostic(
                 path=path,
@@ -880,6 +922,50 @@ def _check_route_conflicts(routes: list[tuple[int, Route]]) -> list[_Finding]:
     return findings
 
 
+def _check_operation_ids(routes: list[tuple[int, Route]], parents: Mapping[ast.AST, ast.AST]) -> list[_Finding]:
+    findings: list[_Finding] = []
+    seen: dict[tuple[int, str, str], Route] = {}
+    reported: set[int] = set()
+    for scope, route in sorted(routes, key=lambda item: item[1].decorator.lineno):
+        if (
+            route.is_hidden
+            or route.path is None
+            or route.method == "*"
+            or "openapi_extra" in route.keywords
+            or _conditional_registration(route.decorator, parents)
+        ):
+            continue
+        operation_id = route.keywords.get("operation_id")
+        if (
+            not isinstance(operation_id, ast.Constant)
+            or not isinstance(operation_id.value, str)
+            or not operation_id.value
+        ):
+            continue
+        key = scope, route.receiver, operation_id.value
+        earlier = seen.get(key)
+        if earlier is None:
+            seen[key] = route
+        elif (earlier.path, earlier.method) != (route.path, route.method) and id(route.decorator) not in reported:
+            findings.append(
+                _Finding(
+                    operation_id,
+                    f"[operation-id] duplicate operation_id `{operation_id.value}`; use a unique ID for each operation.",
+                )
+            )
+            reported.add(id(route.decorator))
+    return findings
+
+
+def _conditional_registration(decorator: ast.Call, parents: Mapping[ast.AST, ast.AST]) -> bool:
+    owner = parents.get(decorator)
+    while owner is not None:
+        if isinstance(owner, (ast.If, ast.Match, ast.Try, ast.TryStar, ast.For, ast.AsyncFor, ast.While)):
+            return True
+        owner = parents.get(owner)
+    return False
+
+
 def _path_pattern(path: str) -> re.Pattern[str] | None:
     parts: list[str] = []
     position = 0