sarj-python-lint 0.73.0__tar.gz → 0.73.2__tar.gz

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.73.0"
+version = "0.73.2"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -30,13 +30,13 @@ Issues = "https://github.com/sarj-ai/standards/issues"
 
 [dependency-groups]
 dev = [
-  "pytest>=9.0",
-  "ruff>=0.16.1",
-  "basedpyright>=1.39",
+  "pytest>=9.1.1",
+  "ruff>=0.16.3",
+  "basedpyright>=1.39.10",
 ]
 
 [build-system]
-requires = ["hatchling==1.31.0"]
+requires = ["hatchling==1.32.0"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/docstring_args_restate_signature.py

@@ -40,7 +40,10 @@ class DocstringArgsRestateSignature(Rule):
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         summary="Argument documentation must add facts beyond the function signature.",
         rationale="Repeating parameter names and types obscures useful behavioral contracts and drifts when signatures change.",
-        remediation="Remove the redundant argument section, or retain it only to document constraints, units, defaults, or semantics absent from the signature.",
+        remediation=(
+            "Delete the human-only docstring or redundant argument section. Express author-controlled semantics with "
+            "names and types; keep hidden constraints or units as a concise local comment."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/docstring_returns_restate_signature.py

@@ -98,7 +98,10 @@ class DocstringReturnsRestateSignature(Rule):
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         summary="Return documentation must add facts beyond the function name and annotation.",
         rationale="Repeating the return type or function name adds noise and can become stale without explaining the result's semantics.",
-        remediation="Remove the redundant return section, or document identity, units, constraints, or other behavior absent from the signature.",
+        remediation=(
+            "Delete the human-only docstring or redundant return section. Express author-controlled identity and "
+            "units with names and types; keep hidden constraints as a concise local comment."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/duplicated_override_docstring.py

@@ -47,7 +47,10 @@ class DuplicatedOverrideDocstring(Rule):
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         summary="Remove an override docstring copied verbatim from its local base method.",
         rationale="Inherited documentation is already discoverable, while a duplicate adds a second copy that can drift.",
-        remediation="Delete the copied docstring, or rewrite it only when the override has behavior-specific information to add.",
+        remediation=(
+            "Delete the copied docstring. If author-controlled override code is unclear, clarify names or extract a "
+            "helper; keep behavior-specific differences as a concise comment near the divergent code."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -450,7 +450,10 @@ class NoCommentCruft(Rule):
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         summary="Comment repeats code, preserves dead code, or adds a decorative section marker.",
         rationale="Mechanical narration and dead code obscure the constraints and rationale that comments should preserve.",
-        remediation="Delete the cruft and keep only concise comments that explain a non-obvious reason or constraint.",
+        remediation=(
+            "Delete the cruft. If author-controlled code is unclear without narration, clarify names, types, or "
+            "structure; keep only concise comments for a hidden reason or constraint."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         limitations=(
             "Only standalone comments are classified; trailing comments, docstrings, directives, and referenced notes are excluded.",
@@ -640,7 +643,8 @@ class NoCommentCruft(Rule):
                     code=self.code,
                     message=(
                         f"File-header comment preamble ({len(leading)} lines) — "
-                        "use a module docstring for the why, not a block of comments."
+                        "delete the ceremony; use a descriptive module path and place durable constraints near the "
+                        "code they govern or in maintained documentation."
                     ),
                     column_encoding=ColumnEncoding.CODEPOINTS,
                 )

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/no_long_comment.py

@@ -33,9 +33,15 @@ class NoLongComment(Rule):
     id = "no-long-comment"
     code = "SARJ091"
     documentation = RuleDocumentation(
-        summary="Long docstrings must use deliberate documentation structure or technical anchors.",
+        summary=(
+            "Unstructured docstring prose wall — delete it; clarify author-controlled names, types, and structure or "
+            "move durable design context to maintained documentation."
+        ),
         rationale="An unstructured prose wall is difficult to scan and often hides a contract that belongs in clearer code or durable structured documentation.",
-        remediation="Clarify the code or restructure the docstring with paragraphs, lists, code, paths, links, or other meaningful technical anchors.",
+        remediation=(
+            "Delete human-only prose and clarify names, types, or structure. Keep machine-consumed documentation; move "
+            "broader design context to maintained documentation."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/no_restated_comment.py

@@ -217,9 +217,15 @@ class NoRestatedComment(Rule):
     id: str = "no-restated-comment"
     code: str = "SARJ049"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Comment restates the statement immediately below it.",
+        summary=(
+            "Comment restates the next statement — delete it; clarify an author-controlled name or extract a named "
+            "helper if the code is unclear."
+        ),
         rationale="Comments that repeat code add reading cost and can become stale without explaining intent.",
-        remediation="Delete the comment or replace it with context the statement cannot express.",
+        remediation=(
+            "Delete the comment. If author-controlled code is unclear without it, clarify a name or extract a named "
+            "helper; keep comments only for context the statement cannot express."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.SUGGESTION,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/no_typed_doc_sections.py

@@ -27,7 +27,10 @@ class NoTypedDocSections(Rule):
     documentation = RuleDocumentation(
         summary="Docstring sections must not repeat types already present in a fully typed signature.",
         rationale="Duplicated type spellings drift from annotations and add noise without strengthening the behavioral contract.",
-        remediation="Remove the repeated type while retaining behavioral facts, constraints, units, and error conditions.",
+        remediation=(
+            "Delete the human-only docstring or repeated type. Express author-controlled contracts with names and "
+            "annotations; keep hidden constraints, units, or error conditions as a concise local comment."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/no_unnecessary_docstring.py

@@ -39,6 +39,11 @@ _OPENAI_TOOL_DECORATORS = frozenset({"agents.function_tool"})
 _PYDANTIC_DOC_DECORATORS = frozenset({"pydantic.computed_field"})
 _FASTAPI_CONSTRUCTORS = frozenset({"fastapi.APIRouter", "fastapi.FastAPI"})
 _FASTAPI_ROUTE_METHODS = frozenset({"api_route", "delete", "get", "head", "options", "patch", "post", "put", "trace"})
+_TYPER_CONSTRUCTORS = frozenset({"typer.Typer"})
+_TYPER_DOC_METHODS = frozenset({"callback", "command"})
+_CLICK_DOC_DECORATORS = frozenset({"click.command", "click.group"})
+_CLICK_GROUP_CONSTRUCTORS = frozenset({"click.Group"})
+_CLICK_GROUP_METHODS = frozenset({"command", "group"})
 _KNOWN_DECORATORS = frozenset(
     {
         "builtins.property",
@@ -78,14 +83,18 @@ class NoUnnecessaryDocstring(ProjectRule):
     id: str = "no-unnecessary-docstring"
     code: str = "SARJ420"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Keep docstrings only when a machine or framework consumes them.",
+        summary=(
+            "No docstring consumer detected — delete it; make author-controlled names, types, and structure explain "
+            "the code."
+        ),
         rationale=(
-            "Human-only docstrings duplicate names, signatures, and nearby code while creating a second prose surface "
-            "that agents expand and maintainers must review."
+            "A docstring with no detected consumer makes code depend on prose for ordinary meaning and creates a "
+            "second maintenance surface that agents expand and maintainers must review."
         ),
         remediation=(
-            "Delete the docstring; move a genuinely hidden local invariant to one concise comment, or suppress SARJ420 "
-            "when an external documentation consumer cannot be detected mechanically."
+            "Delete the docstring. If author-controlled code is unclear without it, clarify names, types, and structure "
+            "or extract a small named helper. Keep a genuinely hidden invariant as one concise local comment. When "
+            "external tooling consumes __doc__, use an exact SARJ420 suppression that names the consumer."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
@@ -98,6 +107,10 @@ class NoUnnecessaryDocstring(ProjectRule):
                 "The rule is intentionally default-deny: public API documentation without mechanically visible "
                 "consumption needs an auditable SARJ420 suppression."
             ),
+            (
+                "Dynamic Click or Typer decorator options are conservatively treated as possible help consumers; "
+                "explicit non-None help leaves the docstring eligible."
+            ),
         ),
         examples=(
             RuleExample(
@@ -143,9 +156,13 @@ class NoUnnecessaryDocstring(ProjectRule):
         explicitly_consumed = _explicit_docstring_consumers(tree, frozenset(owner_keys.values()))
         shadowed = _module_bound_names(tree)
         imports = _import_bindings(tree, shadowed)
-        fastapi_consumed = _fastapi_docstring_consumers(tree, imports)
-        schema_consumed = _schema_docstring_consumers(tree, imports)
-        project_schema_consumed = _project_schema_docstring_consumers(self._project_indexes, path, tree)
+        consumed_owner_ids = (
+            _fastapi_docstring_consumers(tree, imports)
+            | _typer_docstring_consumers(tree, imports)
+            | _click_group_docstring_consumers(tree, imports)
+            | _schema_docstring_consumers(tree, imports)
+            | _project_schema_docstring_consumers(self._project_indexes, path, tree)
+        )
         source_lines = source.splitlines()
         diagnostics: list[Diagnostic] = []
         for owner in _docstring_owners(tree):
@@ -159,9 +176,7 @@ class NoUnnecessaryDocstring(ProjectRule):
             owner_imports, owner_shadowed = _module_environment_before(tree, owner_line)
             if (
                 _is_syntax_required(owner)
-                or id(owner) in fastapi_consumed
-                or id(owner) in schema_consumed
-                or id(owner) in project_schema_consumed
+                or id(owner) in consumed_owner_ids
                 or _framework_consumes_docstring(owner, owner_imports, owner_shadowed)
             ):
                 continue
@@ -406,7 +421,9 @@ def _framework_consumes_docstring(
         return False
     for decorator in owner.decorator_list:
         target = decorator.func if isinstance(decorator, ast.Call) else decorator
-        name = _resolve_imported_name(target, imports)
+        dotted = _dotted_name(target)
+        head = None if dotted is None else dotted.partition(".")[0]
+        name = _resolve_imported_name(target, imports) if head in imports else None
         if name in _LIVEKIT_TOOL_DECORATORS and (
             not isinstance(decorator, ast.Call) or _livekit_uses_docstring(decorator)
         ):
@@ -419,9 +436,11 @@ def _framework_consumes_docstring(
             not isinstance(decorator, ast.Call) or _keyword_is_missing_or_none(decorator, "description")
         ):
             return True
+        if name in _CLICK_DOC_DECORATORS and (not isinstance(decorator, ast.Call) or _doc_help_is_implicit(decorator)):
+            return True
         if name in _KNOWN_DECORATORS:
             return True
-        if name == "property" and "property" not in shadowed:
+        if dotted == "property" and "property" not in shadowed:
             return True
     if not isinstance(owner, ast.ClassDef):
         return False
@@ -493,6 +512,10 @@ def _keyword_is_missing_or_none(call: ast.Call, name: str) -> bool:
     return value is None or (isinstance(value, ast.Constant) and value.value is None)
 
 
+def _doc_help_is_implicit(call: ast.Call) -> bool:
+    return _keyword_is_missing_or_none(call, "help")
+
+
 def _livekit_uses_docstring(call: ast.Call) -> bool:
     return not any(
         keyword.arg == "raw_schema" and not (isinstance(keyword.value, ast.Constant) and keyword.value.value is None)
@@ -540,6 +563,77 @@ def _fastapi_docstring_consumers(tree: ast.Module, imports: dict[str, str]) -> f
     return frozenset(consumed)
 
 
+def _typer_docstring_consumers(tree: ast.Module, imports: dict[str, str]) -> frozenset[int]:
+    consumed: set[int] = set()
+
+    def visit(body: list[ast.stmt], inherited: dict[str, bool]) -> None:
+        bindings = dict(inherited)
+        for statement in body:
+            if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                if any(_is_typer_callback(decorator, bindings) for decorator in statement.decorator_list):
+                    consumed.add(id(statement))
+                nested = dict(bindings)
+                if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    for argument in (
+                        *statement.args.posonlyargs,
+                        *statement.args.args,
+                        *statement.args.kwonlyargs,
+                    ):
+                        nested[argument.arg] = (
+                            argument.annotation is not None
+                            and _resolve_imported_name(argument.annotation, imports) in _TYPER_CONSTRUCTORS
+                        )
+                    if statement.args.vararg is not None:
+                        nested[statement.args.vararg.arg] = False
+                    if statement.args.kwarg is not None:
+                        nested[statement.args.kwarg.arg] = False
+                visit(statement.body, nested)
+                bindings[statement.name] = False
+                continue
+            if isinstance(statement, (ast.Assign, ast.AnnAssign)):
+                targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
+                value = statement.value
+                is_receiver = _is_typer_receiver_value(value, bindings, imports)
+                for target in targets:
+                    if isinstance(target, ast.Name):
+                        bindings[target.id] = is_receiver
+
+    visit(tree.body, {})
+    return frozenset(consumed)
+
+
+def _click_group_docstring_consumers(tree: ast.Module, imports: dict[str, str]) -> frozenset[int]:
+    consumed: set[int] = set()
+
+    def visit(body: list[ast.stmt], inherited: dict[str, bool]) -> None:
+        bindings = dict(inherited)
+        for statement in body:
+            if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                group_decorator = next(
+                    (
+                        decorator
+                        for decorator in statement.decorator_list
+                        if _is_click_group_decorator(decorator, imports)
+                    ),
+                    None,
+                )
+                if any(_is_click_group_callback(decorator, bindings) for decorator in statement.decorator_list):
+                    consumed.add(id(statement))
+                visit(statement.body, bindings)
+                bindings[statement.name] = group_decorator is not None
+                continue
+            if isinstance(statement, (ast.Assign, ast.AnnAssign)):
+                targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
+                value = statement.value
+                is_receiver = _is_click_group_receiver_value(value, bindings, imports)
+                for target in targets:
+                    if isinstance(target, ast.Name):
+                        bindings[target.id] = is_receiver
+
+    visit(tree.body, {})
+    return frozenset(consumed)
+
+
 def _schema_docstring_consumers(tree: ast.Module, imports: dict[str, str]) -> frozenset[int]:
     classes = {statement.name: statement for statement in ast.walk(tree) if isinstance(statement, ast.ClassDef)}
     consumed: set[str] = set()
@@ -594,6 +688,53 @@ def _is_fastapi_route(decorator: ast.expr, bindings: dict[str, bool]) -> bool:
     return description is None or (isinstance(description, ast.Constant) and not description.value)
 
 
+def _is_typer_receiver_value(node: ast.AST | None, bindings: dict[str, bool], imports: dict[str, str]) -> bool:
+    if isinstance(node, ast.Name):
+        return bindings.get(node.id, False) or _resolve_imported_name(node, imports) in _TYPER_CONSTRUCTORS
+    return isinstance(node, ast.Call) and (
+        _resolve_imported_name(node.func, imports) in _TYPER_CONSTRUCTORS
+        or (isinstance(node.func, ast.Name) and bindings.get(node.func.id, False))
+    )
+
+
+def _is_typer_callback(decorator: ast.expr, bindings: dict[str, bool]) -> bool:
+    if not isinstance(decorator, ast.Call) or not isinstance(decorator.func, ast.Attribute):
+        return False
+    receiver = decorator.func.value
+    return (
+        isinstance(receiver, ast.Name)
+        and bindings.get(receiver.id, False)
+        and decorator.func.attr in _TYPER_DOC_METHODS
+        and _doc_help_is_implicit(decorator)
+    )
+
+
+def _is_click_group_decorator(decorator: ast.expr, imports: dict[str, str]) -> bool:
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    return _resolve_imported_name(target, imports) == "click.group"
+
+
+def _is_click_group_receiver_value(node: ast.AST | None, bindings: dict[str, bool], imports: dict[str, str]) -> bool:
+    if isinstance(node, ast.Name):
+        return bindings.get(node.id, False) or _resolve_imported_name(node, imports) in _CLICK_GROUP_CONSTRUCTORS
+    return isinstance(node, ast.Call) and (
+        _resolve_imported_name(node.func, imports) in _CLICK_GROUP_CONSTRUCTORS
+        or (isinstance(node.func, ast.Name) and bindings.get(node.func.id, False))
+    )
+
+
+def _is_click_group_callback(decorator: ast.expr, bindings: dict[str, bool]) -> bool:
+    if not isinstance(decorator, ast.Call) or not isinstance(decorator.func, ast.Attribute):
+        return False
+    receiver = decorator.func.value
+    return (
+        isinstance(receiver, ast.Name)
+        and bindings.get(receiver.id, False)
+        and decorator.func.attr in _CLICK_GROUP_METHODS
+        and _doc_help_is_implicit(decorator)
+    )
+
+
 def _module_bound_names(tree: ast.Module) -> frozenset[str]:
     names: set[str] = set()
     for statement in tree.body:

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/redundant_class_docstring.py

@@ -35,9 +35,15 @@ class RedundantClassDocstring(Rule):
     id: str = "redundant-class-docstring"
     code: str = "SARJ085"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Class docstrings must add information beyond the class name and bases.",
+        summary=(
+            "Class docstring restates the declaration — delete it; clarify author-controlled names, fields, or types "
+            "if the role is unclear."
+        ),
         rationale="Restating a class declaration adds maintenance cost without helping a reader understand its contract.",
-        remediation="Delete the redundant docstring or document an invariant, lifetime, exclusion, or other fact absent from the declaration.",
+        remediation=(
+            "Delete the docstring and clarify author-controlled names, fields, or types. Keep a hidden invariant, "
+            "lifetime, or exclusion as a concise comment near its enforcement."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/redundant_docstring.py

@@ -63,9 +63,15 @@ class RedundantDocstring(Rule):
     id: str = "redundant-docstring"
     code: str = "SARJ050"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Docstring only restates the signature — delete the whole docstring or document behavior callers cannot infer.",
+        summary=(
+            "Docstring only restates the signature — delete the whole docstring; clarify author-controlled names and "
+            "types if the contract is unclear."
+        ),
         rationale="Restating a clear name and signature creates maintenance work without helping callers.",
-        remediation="Delete the docstring or document behavior, constraints, side effects, or failure modes not evident from the signature.",
+        remediation=(
+            "Delete the docstring and clarify author-controlled names, types, or structure. Keep a concise local "
+            "comment only for a hidden constraint, side effect, or failure mode."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.SUGGESTION,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/redundant_module_docstring.py

@@ -55,9 +55,15 @@ class RedundantModuleDocstring(Rule):
     id: str = "redundant-module-docstring"
     code: str = "SARJ099"
     documentation = RuleDocumentation(
-        summary="Module docstrings must add information beyond the file path.",
+        summary=(
+            "Module docstring restates the file path — delete it; clarify the author-controlled module path or exports "
+            "if the purpose is unclear."
+        ),
         rationale="A one-line restatement of a module path duplicates information already visible to readers and search tools.",
-        remediation="Delete the redundant docstring or document an invariant, boundary, consumer, or compatibility constraint.",
+        remediation=(
+            "Delete the docstring and clarify the author-controlled module path or exports. Keep durable boundaries "
+            "and compatibility constraints near the code they govern or in maintained documentation."
+        ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(

{sarj_python_lint-0.73.0 → sarj_python_lint-0.73.2}/src/sarj_python_lint/rules/restated_test_docstring.py

@@ -128,7 +128,10 @@ class RestatedTestDocstring(Rule):
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         summary="Test docstrings must add information beyond the test name and body.",
         rationale="A docstring that narrates visible test code creates duplicate prose that can drift without explaining the regression or contract.",
-        remediation="Delete the redundant docstring, improve the test name, or document a reason or constraint not visible in the test.",
+        remediation=(
+            "Delete the docstring and put the scenario and expected outcome in the test name. Keep a hidden regression "
+            "reason or constraint as one concise local comment."
+        ),
         category=RuleCategory.TESTING,
         autofix=AutofixPolicy.NONE,
         limitations=(