sarj-python-lint 0.45.0__tar.gz → 0.67.2__tar.gz

{sarj_python_lint-0.45.0 → sarj_python_lint-0.67.2}/.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+.astro/
 dist/
 build/
 *.tgz

sarj_python_lint-0.67.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sarj-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sarj_python_lint-0.67.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: sarj-python-lint
+Version: 0.67.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/
+Project-URL: Changelog, https://github.com/sarj-ai/standards/releases
+Project-URL: Repository, https://github.com/sarj-ai/standards
+Project-URL: Issues, https://github.com/sarj-ai/standards/issues
+Author: sarj-ai
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+<!-- Generated by `sarj-standards maintain docs sync`; do not edit. -->
+
+# sarj-python-lint
+
+Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
+
+```bash
+uv tool install sarj-python-lint
+```
+
+```bash
+sarj-python-lint --help
+```
+
+[Documentation](https://code-standards.sarj.ai/rules/python/) · [Source](https://github.com/sarj-ai/standards)

sarj_python_lint-0.67.2/README.md

@@ -0,0 +1,15 @@
+<!-- Generated by `sarj-standards maintain docs sync`; do not edit. -->
+
+# sarj-python-lint
+
+Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
+
+```bash
+uv tool install sarj-python-lint
+```
+
+```bash
+sarj-python-lint --help
+```
+
+[Documentation](https://code-standards.sarj.ai/rules/python/) · [Source](https://github.com/sarj-ai/standards)

{sarj_python_lint-0.45.0 → sarj_python_lint-0.67.2}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "sarj-python-lint"
-version = "0.45.0"
+version = "0.67.2"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.14"
 classifiers = [
   "Development Status :: 4 - Beta",
@@ -21,7 +22,9 @@ sarj-python-lint = "sarj_python_lint.__main__:main"
 sarj-ratchet = "sarj_python_lint._ratchet_cli:main"
 
 [project.urls]
-Homepage = "https://github.com/sarj-ai/standards/tree/main/packages/python"
+Homepage = "https://code-standards.sarj.ai/rules/python/"
+Documentation = "https://code-standards.sarj.ai/rules/python/"
+Changelog = "https://github.com/sarj-ai/standards/releases"
 Repository = "https://github.com/sarj-ai/standards"
 Issues = "https://github.com/sarj-ai/standards/issues"
 
@@ -33,7 +36,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling==1.31.0"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
@@ -43,6 +46,7 @@ packages = ["src/sarj_python_lint"]
 include = [
   "src",
   "README.md",
+  "LICENSE",
   "pyproject.toml",
 ]
 exclude = [
@@ -53,6 +57,9 @@ exclude = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+  "illustrative: executes reviewed examples published in the generated rule catalog",
+]
 
 # Dogfooding: linted/formatted by this repo's own published config (root-synced).
 [tool.ruff]

sarj_python_lint-0.67.2/src/sarj_python_lint/__init__.py

@@ -0,0 +1,7 @@
+"""sarj-python-lint — custom Python lint rules."""
+
+from sarj_python_lint._ratchet_cli import main as run_ratchet
+from sarj_python_lint._version import __version__
+
+
+__all__ = ["__version__", "run_ratchet"]

sarj_python_lint-0.67.2/src/sarj_python_lint/__main__.py

@@ -0,0 +1,380 @@
+"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] [--baseline <json>] <files>."""
+
+from __future__ import annotations
+
+import argparse
+import ast
+from collections import Counter
+import json
+from pathlib import Path
+import sys
+from types import MappingProxyType
+
+from sarj_python_lint import __version__
+from sarj_python_lint._filesystem import atomic_write_text
+from sarj_python_lint.rule_base import Diagnostic, Severity, is_suppressed
+from sarj_python_lint.rules import REGISTRY
+from sarj_python_lint.rules._paths import clear_path_caches
+
+
+SKIP_DIR_NAMES = frozenset(
+    {
+        "node_modules",
+        ".venv",
+        "venv",
+        ".git",
+        "dist",
+        "build",
+        ".next",
+        "coverage",
+        "__pycache__",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".uv-cache",
+        ".mypy_cache",
+        ".turbo",
+        ".yarn",
+        ".pnpm-store",
+    }
+)
+
+# Skip files larger than this — they are almost always generated/vendored, not
+# hand-written source worth linting.
+_MAX_FILE_BYTES = 500_000
+
+
+def _expand_paths(paths: list[Path]) -> list[Path]:
+    out: list[Path] = []
+    for p in paths:
+        if not p.exists():
+            msg = f"input does not exist: {p}"
+            raise ValueError(msg)
+        if p.is_file():
+            try:
+                if p.stat().st_size <= _MAX_FILE_BYTES:
+                    out.append(p)
+            except OSError:
+                pass
+            continue
+        for child in p.rglob("*.py"):
+            if not child.is_file():
+                continue
+            if any(part in SKIP_DIR_NAMES for part in child.parts):
+                continue
+            try:
+                if child.stat().st_size > _MAX_FILE_BYTES:
+                    continue
+            except OSError:
+                continue
+            out.append(child)
+    return out
+
+
+def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
+    unknown = [rid for rid in rule_ids if rid not in REGISTRY]
+    if unknown:
+        sys.stderr.write(f"unknown rule(s): {', '.join(unknown)}\n")
+        sys.stderr.write(f"available: {', '.join(sorted(REGISTRY))}\n")
+        raise SystemExit(2)
+    rules = [REGISTRY[rid]() for rid in rule_ids]
+    clear_path_caches()
+    expanded = _expand_paths(paths)
+    diags: list[Diagnostic] = []
+    for p in expanded:
+        try:
+            source = p.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        source_lines = source.splitlines()
+        raw = [diagnostic for rule in rules for diagnostic in rule.check(p, source)]
+        diags.extend(
+            diagnostic
+            for diagnostic in deduplicate_diagnostics(
+                [diagnostic for diagnostic in raw if not is_suppressed(source_lines, diagnostic.line, diagnostic.code)],
+                source=source,
+            )
+        )
+    return diags
+
+
+def analyze(
+    rule_ids: list[str],
+    paths: list[Path],
+    *,
+    baseline: Path | None = None,
+    root: Path | None = None,
+) -> list[Diagnostic]:
+    """Return native diagnostics without rendering CLI output."""
+    diagnostics = _check(rule_ids, paths)
+    return diagnostics if baseline is None else _apply_baseline(diagnostics, _read_baseline(baseline), root=root)
+
+
+_DIAGNOSTIC_PRECEDENCE = MappingProxyType(
+    {
+        "SARJ003": frozenset({"SARJ080"}),
+        "SARJ084": frozenset({"SARJ050", "SARJ091"}),
+        "SARJ088": frozenset({"SARJ050", "SARJ085", "SARJ091"}),
+        "SARJ092": frozenset({"SARJ086", "SARJ087"}),
+        "SARJ093": frozenset({"SARJ034"}),
+    }
+)
+
+
+def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = None) -> list[Diagnostic]:
+    """Keep the most specific remediation at a source location."""
+    codes = frozenset(diagnostic.code for diagnostic in diags)
+    needs_docstring_owners = "SARJ092" in codes and not codes.isdisjoint(_DIAGNOSTIC_PRECEDENCE["SARJ092"])
+    docstring_owners = _docstring_owner_locations(source) if source is not None and needs_docstring_owners else {}
+    needs_signature_owners = "SARJ093" in codes and "SARJ034" in codes
+    signature_owners = (
+        _function_signature_owner_locations(source) if source is not None and needs_signature_owners else {}
+    )
+
+    def owner_location(diagnostic: Diagnostic) -> tuple[int, int]:
+        if diagnostic.code in {"SARJ034", "SARJ093"}:
+            return signature_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
+        return docstring_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
+
+    present: dict[tuple[Path, int, int], dict[str, set[Severity]]] = {}
+    for diagnostic in diags:
+        line, col = owner_location(diagnostic)
+        by_code = present.setdefault((diagnostic.path, line, col), {})
+        by_code.setdefault(diagnostic.code, set()).add(diagnostic.severity)
+    suppressed = {
+        (location, generic, generic_severity)
+        for location, codes in present.items()
+        for specific, generics in _DIAGNOSTIC_PRECEDENCE.items()
+        if specific in codes
+        for generic in generics
+        for generic_severity in codes.get(generic, set())
+        if generic_severity is Severity.WARNING or Severity.ERROR in codes[specific]
+    }
+    return [
+        diagnostic
+        for diagnostic in diags
+        if (
+            (
+                (
+                    diagnostic.path,
+                    *owner_location(diagnostic),
+                ),
+                diagnostic.code,
+                diagnostic.severity,
+            )
+            not in suppressed
+        )
+    ]
+
+
+def _function_signature_owner_locations(source: str) -> dict[int, tuple[int, int]]:
+    """Map signature lines to their function opening for cross-rule precedence."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return {}
+    owners: dict[int, tuple[int, int]] = {}
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        body_line = node.body[0].lineno if node.body else node.lineno + 1
+        end_line = max(node.lineno, body_line - 1)
+        owners.update(dict.fromkeys(range(node.lineno, end_line + 1), (node.lineno, node.col_offset + 1)))
+    return owners
+
+
+def _docstring_owner_locations(source: str) -> dict[int, tuple[int, int]]:
+    """Map every physical docstring line to the opening expression that owns it."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        tree = None
+    if tree is None:
+        return {}
+    owners: dict[int, tuple[int, int]] = {}
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)) or not node.body:
+            continue
+        expression = node.body[0]
+        if not (
+            isinstance(expression, ast.Expr)
+            and isinstance(expression.value, ast.Constant)
+            and isinstance(expression.value.value, str)
+        ):
+            continue
+        location = (expression.lineno, expression.col_offset + 1)
+        lines = range(expression.lineno, (expression.end_lineno or expression.lineno) + 1)
+        owners.update(dict.fromkeys(lines, location))
+    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
+
+
+def _explain(wanted: str) -> int:
+    """Print a rule's description and its derived examples link."""
+    key = wanted.strip()
+    cls = REGISTRY.get(key) or next((c for c in REGISTRY.values() if c.code.upper() == key.upper()), None)
+    if cls is None:
+        sys.stderr.write(f"unknown rule: {wanted}\navailable: {', '.join(sorted(REGISTRY))}\n")
+        return 2
+    sys.stdout.write(f"{cls.code}  {cls.id}\n{cls.description}\nexamples: {cls.examples_url()}\n")
+    return 0
+
+
+def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
+    counts: dict[str, dict[str, int]] = {}
+    for d in diags:
+        if d.severity is Severity.WARNING:
+            continue
+        key = _baseline_path(d.path)
+        counts.setdefault(key, {})
+        counts[key][d.code] = counts[key].get(d.code, 0) + 1
+    return counts
+
+
+def _baseline_path(path: Path, *, root: Path | None = None) -> str:
+    """Make baselines portable when a caller supplies repository-absolute paths."""
+    try:
+        return path.resolve().relative_to((Path.cwd() if root is None else root).resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _read_baseline(path: Path) -> dict[str, dict[str, int]]:
+    """Load a baseline file, keeping only well-formed `{path: {CODE: count}}` entries."""
+    raw: object = json.loads(  # pyright: ignore[reportAny] — json.loads is an untyped stdlib boundary; the shape is narrowed below
+        path.read_text(encoding="utf-8")
+    )
+    if not isinstance(raw, dict):
+        return {}
+    counts: dict[str, dict[str, int]] = {}
+    for file_key, per_code in raw.items():  # pyright: ignore[reportUnknownVariableType] — json.loads yields Any leaves
+        if not isinstance(file_key, str) or not isinstance(per_code, dict):
+            continue
+        counts[file_key] = {
+            code: n
+            for code, n in per_code.items()  # pyright: ignore[reportUnknownVariableType] — same
+            if isinstance(code, str) and isinstance(n, int)
+        }
+    return counts
+
+
+def _apply_baseline(
+    diags: list[Diagnostic],
+    baseline: dict[str, dict[str, int]],
+    *,
+    root: Path | None = None,
+) -> list[Diagnostic]:
+    """Suppress up to the baselined count per (path, code); excess diags survive."""
+    seen: Counter[tuple[str, str]] = Counter()
+    out: list[Diagnostic] = []
+    for d in diags:
+        if d.severity is Severity.WARNING:
+            out.append(d)
+            continue
+        path_key = _baseline_path(d.path, root=root)
+        key = (path_key, d.code)
+        seen[key] += 1
+        # The raw lookup preserves compatibility with baselines written before
+        # repository-relative keys were introduced.
+        allowance = max(
+            baseline.get(path_key, {}).get(d.code, 0),
+            baseline.get(str(d.path), {}).get(d.code, 0),
+        )
+        if seen[key] > allowance:
+            out.append(d)
+    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)
+
+    try:
+        diags = analyze(args.rule, args.files)
+    except (OSError, ValueError) as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+    if args.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")
+        except OSError as exc:
+            sys.stderr.write(f"error: cannot write baseline {args.update_baseline}: {exc}\n")
+            return 2
+        sys.stdout.write(
+            f"baseline written: {args.update_baseline} "
+            f"({blocking} blocking diagnostics over {len(counts)} files; {warnings} warnings excluded)\n"
+        )
+        return 0
+    if args.baseline is not None:
+        try:
+            diags = _apply_baseline(diags, _read_baseline(args.baseline))
+        except (OSError, ValueError) as exc:
+            sys.stderr.write(f"error: invalid baseline {args.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
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sarj_python_lint-0.67.2/src/sarj_python_lint/_filesystem.py

@@ -0,0 +1,31 @@
+"""Small safe filesystem primitives shared by command-line workflows."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import tempfile
+
+
+def atomic_write_text(path: Path, contents: str) -> None:
+    """Replace an existing-parent destination atomically."""
+    if not path.parent.is_dir():
+        msg = f"baseline parent does not exist: {path.parent}"
+        raise OSError(msg)
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            handle.write(contents)
+            handle.flush()
+            os.fsync(handle.fileno())
+        Path(temporary).replace(path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)