sarj-python-lint 0.44.0__tar.gz → 0.46.0__tar.gz

{sarj_python_lint-0.44.0 → sarj_python_lint-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.44.0
+Version: 0.46.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
@@ -28,7 +28,7 @@ uv tool install sarj-python-lint
 
 ```yaml
 - repo: https://github.com/sarj-ai/standards
-  rev: python-v0.44.0
+  rev: python-v0.46.0
   hooks:
     - id: sarj-no-sequential-await
     - id: sarj-inefficient-string-concat-in-loop
@@ -36,6 +36,7 @@ uv tool install sarj-python-lint
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries
     - id: sarj-fastapi-openapi-contract            # SARJ094
+    - id: sarj-no-hidden-constructor-fallback      # SARJ095 (warning)
     - id: sarj-prefer-class-row
     - id: sarj-prefer-timedelta-for-durations
     - id: sarj-prefer-struct-over-namedtuple
@@ -61,6 +62,29 @@ function-local framework imports, imported router instances and the assembled
 Existing projects can adopt the default-enabled rule with `--update-baseline`
 and then shrink that baseline as endpoint contracts are repaired.
 
+### Hidden constructor settings fallback (0.45.0)
+
+`SARJ095` warns when a keyword-only constructor parameter defaults to `None`
+and the constructor silently replaces it with a proven pydantic-settings value.
+The effective dependency is invisible at the call site, and `value or
+settings.VALUE` also treats an explicit falsey value as omitted. Make the
+argument required and resolve the setting at the application composition root;
+the annotation may remain nullable when `None` is still a valid explicit value.
+
+The rule resolves same-module settings objects, imports, aliases and re-exports
+back to an instance of a `pydantic_settings.BaseSettings` subclass. Literal and
+enum defaults, mutable-container initialization, arbitrary factories and
+clients, module constants, environment-variable APIs, other parameters and
+instance state are deliberately outside v1. No autofix is offered because
+changing constructor optionality requires coordinated call-site edits.
+
+Measured over 4,638 tracked Python files in 33 first-party repositories: three
+constructor warnings across two repositories, all three actionable. A pinned
+15-repository OSS sweep covered 29,203 files and produced zero reports, which is
+compatibility evidence rather than a precision claim. An environment-variable
+arm was rejected before shipping: it reported a public first-party library and
+two intentional LiteLLM integration constructors, all non-actionable.
+
 ### Test-quality rules (0.15.0)
 
 Mined from an AST audit of ~7,500 test functions across two production repos.

{sarj_python_lint-0.44.0 → sarj_python_lint-0.46.0}/README.md

@@ -10,7 +10,7 @@ uv tool install sarj-python-lint
 
 ```yaml
 - repo: https://github.com/sarj-ai/standards
-  rev: python-v0.44.0
+  rev: python-v0.46.0
   hooks:
     - id: sarj-no-sequential-await
     - id: sarj-inefficient-string-concat-in-loop
@@ -18,6 +18,7 @@ uv tool install sarj-python-lint
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries
     - id: sarj-fastapi-openapi-contract            # SARJ094
+    - id: sarj-no-hidden-constructor-fallback      # SARJ095 (warning)
     - id: sarj-prefer-class-row
     - id: sarj-prefer-timedelta-for-durations
     - id: sarj-prefer-struct-over-namedtuple
@@ -43,6 +44,29 @@ function-local framework imports, imported router instances and the assembled
 Existing projects can adopt the default-enabled rule with `--update-baseline`
 and then shrink that baseline as endpoint contracts are repaired.
 
+### Hidden constructor settings fallback (0.45.0)
+
+`SARJ095` warns when a keyword-only constructor parameter defaults to `None`
+and the constructor silently replaces it with a proven pydantic-settings value.
+The effective dependency is invisible at the call site, and `value or
+settings.VALUE` also treats an explicit falsey value as omitted. Make the
+argument required and resolve the setting at the application composition root;
+the annotation may remain nullable when `None` is still a valid explicit value.
+
+The rule resolves same-module settings objects, imports, aliases and re-exports
+back to an instance of a `pydantic_settings.BaseSettings` subclass. Literal and
+enum defaults, mutable-container initialization, arbitrary factories and
+clients, module constants, environment-variable APIs, other parameters and
+instance state are deliberately outside v1. No autofix is offered because
+changing constructor optionality requires coordinated call-site edits.
+
+Measured over 4,638 tracked Python files in 33 first-party repositories: three
+constructor warnings across two repositories, all three actionable. A pinned
+15-repository OSS sweep covered 29,203 files and produced zero reports, which is
+compatibility evidence rather than a precision claim. An environment-variable
+arm was rejected before shipping: it reported a public first-party library and
+two intentional LiteLLM integration constructors, all non-actionable.
+
 ### Test-quality rules (0.15.0)
 
 Mined from an AST audit of ~7,500 test functions across two production repos.

{sarj_python_lint-0.44.0 → sarj_python_lint-0.46.0}/pyproject.toml

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

{sarj_python_lint-0.44.0 → sarj_python_lint-0.46.0}/src/sarj_python_lint/__main__.py

@@ -25,6 +25,7 @@ SKIP_DIR_NAMES = {
     "__pycache__",
     ".pytest_cache",
     ".ruff_cache",
+    ".uv-cache",
     ".mypy_cache",
     ".turbo",
     ".yarn",

{sarj_python_lint-0.44.0 → sarj_python_lint-0.46.0}/src/sarj_python_lint/rules/_comments.py

@@ -9,6 +9,7 @@ import tokenize
 from typing import TYPE_CHECKING, NamedTuple
 
 from sarj_python_lint.rule_base import parse_or_none
+from sarj_python_lint.rules._ast_index import nodes
 
 
 if TYPE_CHECKING:
@@ -498,7 +499,7 @@ def statement_comment_walls(
         return {}
     comments = {line: (col, body) for line, col, body in standalone}
     walls: dict[int, frozenset[int]] = {}
-    for owner in ast.walk(tree):
+    for owner in nodes(tree, ast.AST):
         for value in _owned_statement_lists(owner):
             statements = [item for item in value if _is_wall_statement(item)]
             if len(statements) < _WALL_MIN_STATEMENTS:

{sarj_python_lint-0.44.0 → sarj_python_lint-0.46.0}/src/sarj_python_lint/rules/_prose_budget.py

@@ -10,6 +10,7 @@ import tokenize
 from typing import TYPE_CHECKING, Final
 
 from sarj_python_lint.rule_base import parse_or_none
+from sarj_python_lint.rules._ast_index import nodes
 from sarj_python_lint.rules._docstrings import PROMPT_DECORATOR_MARKERS, decorator_markers, sections
 from sarj_python_lint.rules._paths import is_generated
 
@@ -53,6 +54,9 @@ class ProseGroup:
     typed_sections: frozenset[str] = frozenset()
 
 
+_last_groups: tuple[str, str, tuple[ProseGroup, ...]] | None = None
+
+
 def sentence_units(text: str) -> int:
     """Count prose sentences and unpunctuated list items deterministically."""
     text = _without_examples_metadata(text)
@@ -98,6 +102,17 @@ def _without_examples_metadata(text: str) -> str:
 
 def groups(path: Path, source: str) -> list[ProseGroup]:
     """Extract docstrings and contiguous own-line comment runs from one file."""
+    global _last_groups  # ruff: ignore[global-statement] -- rules run sequentially per file.
+    path_key = str(path)
+    if _last_groups is not None and _last_groups[0] == path_key and _last_groups[1] is source:
+        return list(_last_groups[2])
+    extracted = _extract_groups(path, source)
+    _last_groups = (path_key, source, tuple(extracted))
+    return extracted
+
+
+def _extract_groups(path: Path, source: str) -> list[ProseGroup]:
+    """Perform the shared parse and tokenization once for adjacent prose rules."""
     if is_generated(path, source):
         return []
     tree = parse_or_none(path, source)
@@ -140,8 +155,8 @@ def _comment_run(run: list[tokenize.TokenInfo]) -> ProseGroup:
 
 def _docstring_groups(tree: ast.Module) -> list[ProseGroup]:
     out: list[ProseGroup] = []
-    for node in ast.walk(tree):
-        if not isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)) or not node.body:
+    for node in nodes(tree, ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef):
+        if not node.body:
             continue
         first = node.body[0]
         if not (

{sarj_python_lint-0.44.0 → sarj_python_lint-0.46.0}/src/sarj_python_lint/rules/_registry.py

@@ -37,6 +37,9 @@ from sarj_python_lint.rules.no_first_party_private_import import (
 )
 from sarj_python_lint.rules.no_fstring_in_log import NoFstringInLog
 from sarj_python_lint.rules.no_gen_random_uuid_in_sql import NoGenRandomUuidInSql
+from sarj_python_lint.rules.no_hidden_constructor_fallback import (
+    NoHiddenConstructorFallback,
+)
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_long_comment import NoLongComment
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
@@ -167,6 +170,7 @@ REGISTRY: dict[str, type[Rule]] = {
     TrailingValueNarration.id: TrailingValueNarration,
     NoStdlibLogging.id: NoStdlibLogging,
     NoGenRandomUuidInSql.id: NoGenRandomUuidInSql,
+    NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
     NoFileLevelEscapeHatchNoqa.id: NoFileLevelEscapeHatchNoqa,
     NoOptionalTenantPredicate.id: NoOptionalTenantPredicate,
     NoTautologicalExpect.id: NoTautologicalExpect,