sarj-python-lint 0.80.14__tar.gz → 0.80.17__tar.gz

{sarj_python_lint-0.80.14 → sarj_python_lint-0.80.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.80.14
+Version: 0.80.17
 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,6 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: ruff>=0.16.5
 Requires-Dist: sqlglot==30.18.0
+Requires-Dist: typer==0.27.2
 Description-Content-Type: text/markdown
 
 <!-- Generated by `code-standards maintain docs sync`; do not edit. -->

{sarj_python_lint-0.80.14 → sarj_python_lint-0.80.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.80.14"
+version = "0.80.17"
 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 = ["ruff>=0.16.5", "sqlglot==30.18.0"]
+dependencies = ["ruff>=0.16.5", "sqlglot==30.18.0", "typer==0.27.2"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"

sarj_python_lint-0.80.17/src/sarj_python_lint/__init__.py

@@ -0,0 +1,2 @@
+from sarj_python_lint._ratchet_cli import run_ratchet as run_ratchet
+from sarj_python_lint._version import __version__ as __version__

{sarj_python_lint-0.80.14 → sarj_python_lint-0.80.17}/src/sarj_python_lint/__main__.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
-import argparse
 import ast
 from collections import Counter
+from dataclasses import dataclass
 import json
 from pathlib import Path
 import sys
 from types import MappingProxyType
-from typing import NamedTuple
+from typing import Annotated, NamedTuple
+
+import typer
 
 from sarj_python_lint import __version__
 from sarj_python_lint._analysis_session import AnalysisSession
@@ -236,24 +238,9 @@ def _docstring_owner_locations(source: str) -> dict[int, _OwnerLocation]:
     return owners
 
 
-class _Args(argparse.Namespace):
-    cmd: str | None
-    rule: list[str]
-    # `explain` takes exactly one rule, so it cannot share `--rule`'s list slot
-    # without widening the type and losing the check on every `check` call site.
-    which: str
-    files: list[Path]
-    baseline: Path | None
-    update_baseline: Path | None
-
-    def __init__(self) -> None:
-        super().__init__()
-        self.cmd = None
-        self.rule = []
-        self.which = ""
-        self.files = []
-        self.baseline = None
-        self.update_baseline = None
+@dataclass
+class _Result:
+    code: int = 0
 
 
 def _explain(wanted: str) -> int:
@@ -328,78 +315,98 @@ def _apply_baseline(
     return out
 
 
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="sarj-python-lint",
-        description="Custom Python lint rules.",
-    )
-    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
-    sub = parser.add_subparsers(dest="cmd", required=True)
-
-    check_p = sub.add_parser("check", help="Run rules over files.")
-    check_p.add_argument(
-        "--rule",
-        action="append",
-        required=True,
-        help="Rule ID (repeat for multiple).",
-    )
-    check_p.add_argument(
-        "--baseline",
-        type=Path,
-        help="Per-file shrink-only baseline JSON: {path: {CODE: count}}. Diags up to the baselined count are suppressed.",
-    )
-    check_p.add_argument(
-        "--update-baseline",
-        type=Path,
-        help="Write the current per-file diagnostic counts to this JSON and exit 0.",
-    )
-    check_p.add_argument("files", nargs="+", type=Path)
-
-    sub.add_parser("list-rules", help="List available rule IDs.")
-
-    explain_p = sub.add_parser("explain", help="Print one rule's summary and the links to its examples and evidence.")
-    explain_p.add_argument("which", metavar="rule", help="Rule ID or SARJ code.")
-
-    args = parser.parse_args(argv, namespace=_Args())
-
-    if args.cmd == "list-rules":
-        for rid, cls in sorted(REGISTRY.items()):
-            inst = cls()
-            sys.stdout.write(f"{inst.code:8}  {rid:40}  {inst.description}\n")
-        return 0
-
-    if args.cmd == "explain":
-        return _explain(args.which)
-
+def _run_check(rule: list[str], files: list[Path], baseline: Path | None, update_baseline: Path | None) -> int:
     try:
-        diags = analyze(args.rule, args.files)
+        diags = analyze(rule, files)
     except (OSError, ValueError) as exc:
         sys.stderr.write(f"error: {exc}\n")
         return 2
-    if args.update_baseline is not None:
+    if update_baseline is not None:
         counts = _baseline_counts(diags)
         blocking = sum(d.severity is Severity.ERROR for d in diags)
         warnings = len(diags) - blocking
         try:
-            atomic_write_text(args.update_baseline, json.dumps(counts, indent=2, sort_keys=True) + "\n")
+            atomic_write_text(update_baseline, json.dumps(counts, indent=2, sort_keys=True) + "\n")
         except OSError as exc:
-            sys.stderr.write(f"error: cannot write baseline {args.update_baseline}: {exc}\n")
+            sys.stderr.write(f"error: cannot write baseline {update_baseline}: {exc}\n")
             return 2
         sys.stdout.write(
-            f"baseline written: {args.update_baseline} "
+            f"baseline written: {update_baseline} "
             f"({blocking} blocking diagnostics over {len(counts)} files; {warnings} warnings excluded)\n"
         )
         return 0
-    if args.baseline is not None:
+    if baseline is not None:
         try:
-            diags = _apply_baseline(diags, _read_baseline(args.baseline))
+            diags = _apply_baseline(diags, _read_baseline(baseline))
         except (OSError, ValueError) as exc:
-            sys.stderr.write(f"error: invalid baseline {args.baseline}: {exc}\n")
+            sys.stderr.write(f"error: invalid baseline {baseline}: {exc}\n")
             return 2
     for d in diags:
         sys.stdout.write(d.format() + "\n")
     return 1 if any(d.severity is Severity.ERROR for d in diags) else 0
 
 
+app = typer.Typer(
+    help="Custom Python lint rules.",
+    add_completion=False,
+    no_args_is_help=False,
+    pretty_exceptions_enable=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _show_version(*, value: bool) -> None:
+    if value:
+        sys.stdout.write(f"sarj-python-lint {__version__}\n")
+        raise typer.Exit
+
+
+@app.callback()
+def _root(
+    *,
+    _version: Annotated[bool, typer.Option("--version", callback=_show_version, is_eager=True)] = False,
+) -> None:
+    pass
+
+
+@app.command("list-rules", help="List available rule IDs.")
+def _list_rules() -> None:
+    for rid, cls in sorted(REGISTRY.items()):
+        inst = cls()
+        sys.stdout.write(f"{inst.code:8}  {rid:40}  {inst.description}\n")
+
+
+@app.command("explain", help="Print one rule's summary and the links to its examples and evidence.")
+def _explain_command(
+    context: typer.Context, which: Annotated[str, typer.Argument(metavar="rule", help="Rule ID or SARJ code.")]
+) -> None:
+    context.ensure_object(_Result).code = _explain(which)
+
+
+@app.command("check", help="Run rules over files.")
+def _check_command(
+    context: typer.Context,
+    files: Annotated[list[Path], typer.Argument()],
+    rule: Annotated[list[str], typer.Option("--rule", help="Rule ID (repeat for multiple).")],
+    baseline: Annotated[
+        Path | None, typer.Option(help="Per-file shrink-only baseline JSON: {path: {CODE: count}}.")
+    ] = None,
+    update_baseline: Annotated[
+        Path | None, typer.Option(help="Write current per-file diagnostic counts to JSON and exit 0.")
+    ] = None,
+) -> None:
+    context.ensure_object(_Result).code = _run_check(rule, files, baseline, update_baseline)
+
+
+def main(argv: list[str] | None = None) -> int:
+    result = _Result()
+    try:
+        app(args=argv, prog_name="sarj-python-lint", obj=result)
+    except SystemExit as exc:
+        if exc.code != 0:
+            raise
+    return result.code
+
+
 if __name__ == "__main__":
     sys.exit(main())

{sarj_python_lint-0.80.14 → sarj_python_lint-0.80.17}/src/sarj_python_lint/_ratchet_cli.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
-import argparse
+from dataclasses import dataclass
 import json
 from pathlib import Path
 import subprocess  # ruff: ignore[suspicious-subprocess-import] -- fixed local Ruff introspection only
 import sys
-from typing import TYPE_CHECKING, TypeGuard
+from typing import TYPE_CHECKING, Annotated, TypeGuard
+
+import typer
 
 from sarj_python_lint._filesystem import atomic_write_text
 from sarj_python_lint._version import __version__
@@ -29,7 +31,8 @@ if TYPE_CHECKING:
 _DEFAULT_BASELINE_NAME = "suppression-baseline.json"
 
 
-class _Args(argparse.Namespace):
+@dataclass(frozen=True)
+class _Options:
     root: Path
     baseline: Path | None
     package: list[str]
@@ -38,19 +41,8 @@ class _Args(argparse.Namespace):
     update: bool
     allow_increase: bool
 
-    def __init__(self) -> None:
-        super().__init__()
-        self.root = Path()
-        self.baseline = None
-        self.package = []
-        self.exclude_subtree = []
-        self.per_file_ceiling = None
-        self.update = False
-        self.allow_increase = False
-
 
-def main(argv: list[str] | None = None) -> int:
-    args = _build_parser().parse_args(argv, namespace=_Args())
+def _run(args: _Options) -> int:
     root = args.root.resolve()
     baseline_path = args.baseline if args.baseline is not None else root / _DEFAULT_BASELINE_NAME
 
@@ -180,48 +172,68 @@ def _is_string_object_mapping(value: object) -> TypeGuard[dict[str, object]]:
     return isinstance(value, dict)
 
 
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="sarj-ratchet",
-        description=(
-            "Ratchet on lint/type suppressions: per-code, per-package and per-file ceilings that may only shrink."
+@dataclass
+class _Result:
+    code: int = 0
+
+
+app = typer.Typer(
+    help="Ratchet on lint/type suppressions: per-code, per-package and per-file ceilings that may only shrink.",
+    add_completion=False,
+    no_args_is_help=False,
+    pretty_exceptions_enable=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _show_version(*, value: bool) -> None:
+    if value:
+        sys.stdout.write(f"sarj-ratchet {__version__}\n")
+        raise typer.Exit
+
+
+@app.command()
+def _command(
+    context: typer.Context,
+    *,
+    root: Annotated[Path, typer.Argument(help="tree to scan (default: cwd)")] = Path(),
+    baseline: Annotated[
+        Path | None, typer.Option(help=f"baseline JSON (default: <root>/{_DEFAULT_BASELINE_NAME})")
+    ] = None,
+    package: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--package", help="package directory relative to root (repeatable; default: baseline or auto-discovered)"
         ),
+    ] = None,
+    exclude_subtree: Annotated[
+        list[str] | None, typer.Option("--exclude-subtree", help="root-relative path prefix to skip (repeatable)")
+    ] = None,
+    per_file_ceiling: Annotated[
+        int | None,
+        typer.Option(help=f"max suppressions in any one file (default: baseline or {DEFAULT_PER_FILE_CEILING})"),
+    ] = None,
+    update: Annotated[
+        bool, typer.Option("--update", help="rewrite baseline from current counts (refuses to raise a ceiling)")
+    ] = False,
+    allow_increase: Annotated[
+        bool, typer.Option("--allow-increase", help="with --update: permit ceilings to rise (requires explicit review)")
+    ] = False,
+    _version: Annotated[bool, typer.Option("--version", callback=_show_version, is_eager=True)] = False,
+) -> None:
+    context.ensure_object(_Result).code = _run(
+        _Options(root, baseline, package or [], exclude_subtree or [], per_file_ceiling, update, allow_increase)
     )
-    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
-    parser.add_argument("root", nargs="?", type=Path, default=Path(), help="tree to scan (default: cwd)")
-    parser.add_argument(
-        "--baseline",
-        type=Path,
-        help=f"baseline JSON (default: <root>/{_DEFAULT_BASELINE_NAME})",
-    )
-    parser.add_argument(
-        "--package",
-        action="append",
-        default=[],
-        help="package directory relative to root (repeatable; default: the baseline's, else auto-discovered)",
-    )
-    parser.add_argument(
-        "--exclude-subtree",
-        action="append",
-        default=[],
-        help="root-relative path prefix to skip, e.g. generated client output (repeatable)",
-    )
-    parser.add_argument(
-        "--per-file-ceiling",
-        type=int,
-        help=f"max suppressions in any one file (default: the baseline's, else {DEFAULT_PER_FILE_CEILING})",
-    )
-    parser.add_argument(
-        "--update",
-        action="store_true",
-        help="rewrite the baseline from current counts (refuses to raise a ceiling)",
-    )
-    parser.add_argument(
-        "--allow-increase",
-        action="store_true",
-        help="with --update: permit ceilings to rise (requires explicit review)",
-    )
-    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    result = _Result()
+    try:
+        app(args=argv, prog_name="sarj-ratchet", obj=result)
+    except SystemExit as exc:
+        if exc.code != 0:
+            raise
+    return result.code
 
 
 def _update(
@@ -249,5 +261,8 @@ def _update(
     return 0
 
 
+run_ratchet = main
+
+
 if __name__ == "__main__":
     sys.exit(main())

sarj_python_lint-0.80.17/src/sarj_python_lint/rules/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from sarj_python_lint.rules._registry import REGISTRY as REGISTRY

{sarj_python_lint-0.80.14 → sarj_python_lint-0.80.17}/src/sarj_python_lint/rules/_registry.py

@@ -33,6 +33,7 @@ from sarj_python_lint.rules.no_copied_inherited_docstring import NoCopiedInherit
 from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
 )
+from sarj_python_lint.rules.no_dunder_all import NoDunderAll
 from sarj_python_lint.rules.no_duplicate_dunder_all_entry import NoDuplicateDunderAllEntry
 from sarj_python_lint.rules.no_fastapi_on_event import NoFastapiOnEvent
 from sarj_python_lint.rules.no_file_level_escape_hatch_suppression import (
@@ -91,6 +92,7 @@ from sarj_python_lint.rules.prefer_immutable_module_constant import (
 from sarj_python_lint.rules.prefer_library_fake import PreferLibraryFake
 from sarj_python_lint.rules.prefer_match_assert_never import PreferMatchAssertNever
 from sarj_python_lint.rules.prefer_match_type_dispatch import PreferMatchTypeDispatch
+from sarj_python_lint.rules.prefer_match_value_dispatch import PreferMatchValueDispatch
 from sarj_python_lint.rules.prefer_module_level_constant import (
     PreferModuleLevelConstant,
 )
@@ -217,6 +219,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RequirePortForService.id: RequirePortForService,
         PreferNonNullableCollection.id: PreferNonNullableCollection,
         PreferMatchTypeDispatch.id: PreferMatchTypeDispatch,
+        PreferMatchValueDispatch.id: PreferMatchValueDispatch,
         PreferWalrusRegexMatch.id: PreferWalrusRegexMatch,
         PreferWalrusComprehensionFilter.id: PreferWalrusComprehensionFilter,
         PreferWalrusStreamLoop.id: PreferWalrusStreamLoop,
@@ -224,6 +227,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferSetIsdisjoint.id: PreferSetIsdisjoint,
         PreferSelfDocumentingConstant.id: PreferSelfDocumentingConstant,
         NoDuplicateDunderAllEntry.id: NoDuplicateDunderAllEntry,
+        NoDunderAll.id: NoDunderAll,
         NoCopiedInheritedDocstring.id: NoCopiedInheritedDocstring,
         RedundantClassDocstring.id: RedundantClassDocstring,
         RedundantModuleDocstring.id: RedundantModuleDocstring,
@@ -250,5 +254,3 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         TypedErrorReasons.id: TypedErrorReasons,
     }
 )
-
-__all__ = ["REGISTRY"]

{sarj_python_lint-0.80.14 → sarj_python_lint-0.80.17}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -4,6 +4,7 @@ import ast
 from pathlib import PurePosixPath
 import re
 import tokenize
+import tomllib
 from typing import TYPE_CHECKING, ClassVar, override
 
 from sarj_python_lint.rule_base import (
@@ -227,6 +228,27 @@ _CODING_COOKIE_RE = re.compile(r"coding[:=]\s*[-_.a-zA-Z0-9]+")
 # Only `>>>` arms a doctest block.
 _DOCTEST_PROMPT = ">>>"
 
+_SCRIPT_METADATA_RE = re.compile(r"^# /// script\n(?P<content>(?:#(?: .*)?\n)+)# ///(?=\n|$)", re.MULTILINE)
+
+
+def _script_metadata_lines(source: str, standalone: Sequence[PositionedComment]) -> frozenset[int]:
+    normalized = "\n".join(source.splitlines())
+    matches = list(_SCRIPT_METADATA_RE.finditer(normalized))
+    if len(matches) != 1:
+        return frozenset()
+    match = matches[0]
+    first = normalized.count("\n", 0, match.start()) + 1
+    lines = frozenset(range(first, first + match.group().count("\n") + 1))
+    top_level = {line for line, col, _ in standalone if col == 0}
+    if not lines <= top_level:
+        return frozenset()
+    content = "\n".join(line[2:] if line.startswith("# ") else "" for line in match.group("content").splitlines())
+    try:
+        tomllib.loads(content)
+    except tomllib.TOMLDecodeError:
+        return frozenset()
+    return lines
+
 
 def _is_coding_cookie(body: str) -> bool:
     return bool(_CODING_COOKIE_RE.search(body))
@@ -499,6 +521,8 @@ class NoCommentCruft(Rule):
             standalone, first_code_line = standalone_comments(source)
         except tokenize.TokenError, IndentationError, SyntaxError:
             return []
+        skip = _script_metadata_lines(source, standalone)
+        standalone = [comment for comment in standalone if comment.line not in skip]
         diags: dict[int, Diagnostic] = {}
         by_line = {line: (col, body) for line, col, body in standalone}
         skip = _doctest_block_lines(standalone) | _illustration_block_lines(standalone)