sarj-python-lint 0.43.0__tar.gz → 0.43.2__tar.gz

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/.gitignore

@@ -35,3 +35,4 @@ Thumbs.db
 .claude/*
 !.claude/settings.json
 .worktrees/
+.sarj-private-refs.toml

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.43.0
+Version: 0.43.2
 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
@@ -47,8 +47,7 @@ uv tool install sarj-python-lint
 
 Mined from an AST audit of ~7,500 test functions across two production repos.
 Every one is scoped to test files and carries the false-positive guard that made
-it shippable; the module docstring for each records the population it was
-measured against.
+it shippable; `sarj-python-lint explain` links each rule to its behavioral tests.
 
 ```yaml
     - id: sarj-mock-without-spec                   # SARJ040
@@ -90,8 +89,8 @@ Attribute access (`session._stt`) is out of scope and stays with ruff's
 
 From a 37,918-comment, nine-repo measurement study. All three are
 deletion-class, so each was validated against pydantic / trio / attrs as well as
-the maintained repos before shipping — the counts and the false-positive classes
-each guard was built from are recorded in the rule module docstrings.
+the maintained repos before shipping, with each false-positive guard encoded in
+the behavioral tests linked by `sarj-python-lint explain`.
 
 ```yaml
     - id: sarj-no-restated-comment                 # SARJ049
@@ -278,7 +277,6 @@ duplicated ruff.
 
 ```yaml
     - id: sarj-prefer-fstring-over-concat          # SARJ068
-    - id: sarj-prefer-match-pattern-destructuring  # SARJ069
     - id: sarj-prefer-or-pattern                   # SARJ070
     - id: sarj-require-port-for-service            # SARJ071
 ```

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/README.md

@@ -29,8 +29,7 @@ uv tool install sarj-python-lint
 
 Mined from an AST audit of ~7,500 test functions across two production repos.
 Every one is scoped to test files and carries the false-positive guard that made
-it shippable; the module docstring for each records the population it was
-measured against.
+it shippable; `sarj-python-lint explain` links each rule to its behavioral tests.
 
 ```yaml
     - id: sarj-mock-without-spec                   # SARJ040
@@ -72,8 +71,8 @@ Attribute access (`session._stt`) is out of scope and stays with ruff's
 
 From a 37,918-comment, nine-repo measurement study. All three are
 deletion-class, so each was validated against pydantic / trio / attrs as well as
-the maintained repos before shipping — the counts and the false-positive classes
-each guard was built from are recorded in the rule module docstrings.
+the maintained repos before shipping, with each false-positive guard encoded in
+the behavioral tests linked by `sarj-python-lint explain`.
 
 ```yaml
     - id: sarj-no-restated-comment                 # SARJ049
@@ -260,7 +259,6 @@ duplicated ruff.
 
 ```yaml
     - id: sarj-prefer-fstring-over-concat          # SARJ068
-    - id: sarj-prefer-match-pattern-destructuring  # SARJ069
     - id: sarj-prefer-or-pattern                   # SARJ070
     - id: sarj-require-port-for-service            # SARJ071
 ```

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/pyproject.toml

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

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/src/sarj_python_lint/__main__.py

@@ -102,21 +102,13 @@ class _Args(argparse.Namespace):
 
 
 def _explain(wanted: str) -> int:
-    """Print a rule's summary plus the derived links to its examples and evidence.
-
-    This is the runtime consumer of the one-line module docstring: it is what
-    makes an inaccurate summary visible rather than merely unread.
-
-    """
+    """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
-    summary = (sys.modules[cls.__module__].__doc__ or "").strip().splitlines()
-    sys.stdout.write(
-        f"{cls.code}  {cls.id}\n{summary[0] if summary else cls.description}\nexamples: {cls.examples_url()}\n"
-    )
+    sys.stdout.write(f"{cls.code}  {cls.id}\n{cls.description}\nexamples: {cls.examples_url()}\n")
     return 0
 
 
@@ -131,13 +123,7 @@ def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
 
 
 def _read_baseline(path: Path) -> dict[str, dict[str, int]]:
-    """Load a baseline file, keeping only well-formed `{path: {CODE: count}}` entries.
-
-    `json.loads` returns `Any`, so the shape is narrowed here rather than
-    asserted — a hand-edited baseline should degrade to "not baselined" rather
-    than crash the run or silently suppress on a malformed entry.
-
-    """
+    """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")
     )

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/src/sarj_python_lint/_secret_names.py

@@ -1,7 +1,4 @@
-"""Recognize secret-bearing identifiers for SARJ011 and SARJ012.
-
-Matching uses whole words and excludes metadata and boolean-state names.
-"""
+"""Recognize secret-bearing identifiers for SARJ011 and SARJ012."""
 
 from __future__ import annotations
 
@@ -64,8 +61,7 @@ _INNOCUOUS_WORDS = frozenset(
 # A leading predicate makes the identifier a boolean flag, not a credential.
 _FLAG_PREFIXES = frozenset({"is", "has", "was", "are", "can", "should"})
 
-# camelCase / PascalCase / ALLCAPS / digit run splitter, applied to each
-# snake/kebab segment. `APIKey` -> ["API", "Key"], `authToken` -> ["auth", "Token"].
+# Split camel case, capitals, and digit runs within each underscore-delimited component.
 _CAMEL_RE = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+")
 _SEGMENT_RE = re.compile(r"[^A-Za-z0-9]+")
 

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/src/sarj_python_lint/ratchet.py

@@ -1,41 +1,4 @@
-"""Suppression ratchet: count every escape hatch in a tree and let the count only shrink.
-
-A suppression comment is a decision to stop a checker from doing its job on one
-line. Individually each is often right; collectively they are the only number
-that says whether the codebase is getting more or less checked, and nothing in
-review shows that number. A ratchet makes it visible and one-directional:
-snapshot today's counts into a baseline, then fail any commit that raises one.
-
-Three ceilings apply at once, because each catches a shape the others miss:
-
-* **per code** — `# noqa: TID251` growing from 40 to 41 is a real regression
-  even when the repo total falls, and a code-blind total lets a cleanup
-  elsewhere pay for it.
-* **per package** — a monorepo where one package is well-typed and another is
-  not needs separate floors, or the good package's headroom finances the bad
-  one's debt.
-* **per file** — a global ceiling on any single file, so new suppressions
-  cannot pile into one hot spot while the package total stays flat. Files that
-  already exceeded it when the ceiling landed are grandfathered at their
-  then-current counts and may only shrink.
-
-All four suppression dialects are counted, each under its own key prefix, so
-migrating a suppression from one spelling to another can never hide it:
-
-| key                     | comment form                                    |
-|-------------------------|-------------------------------------------------|
-| `noqa:CODE`             | `x = f()  # noqa: E501`                         |
-| `sarj-noqa:CODE`        | `x = f()  # sarj-noqa: SARJ016 — reason`        |
-| `pyright:CODE`          | `x = f()  # pyright: ignore[reportAny]`         |
-| `type-ignore:CODE`      | `x = f()  # type: ignore[attr-defined]`         |
-| `type-ignore`           | `x = f()  # type: ignore`  (bare)               |
-| `file-noqa:CODE`        | `# ruff: noqa: E501` at file level              |
-| `file-noqa:<blanket>`   | `# ruff: noqa` at file level, no codes          |
-| `file-pyright:RULE`     | `# pyright: reportAny=false` file header        |
-
-Every occurrence on a line counts, not just the first: `f()  # noqa: A  # noqa: B`
-is two suppressions.
-"""
+"""Suppression ratchet: count every escape hatch in a tree and let the count only shrink."""
 
 from __future__ import annotations
 
@@ -100,7 +63,7 @@ class Measurement:
 
 @dataclass(frozen=True, slots=True)
 class Baseline:
-    """The checked-in ceilings. A key absent from `codes`/`packages` has a ceiling of 0."""
+    """Ceilings by code, package, and file so cleanup in one dimension cannot finance debt in another."""
 
     codes: dict[str, int] = field(default_factory=dict[str, int])
     packages: dict[str, int] = field(default_factory=dict[str, int])
@@ -148,13 +111,7 @@ def measure(
     excluded_dir_names: frozenset[str] = DEFAULT_EXCLUDED_DIR_NAMES,
     excluded_subtrees: Iterable[str] = (),
 ) -> Measurement:
-    """Count every suppression under `root`, bucketed by code, package and file.
-
-    `packages` are paths relative to `root`; a package that does not exist
-    contributes 0 rather than raising, so a baseline outliving a rename fails
-    loudly on the package's disappearance rather than crashing.
-
-    """
+    """Count every suppression under `root`, bucketed by code, package and file."""
     codes: Counter[str] = Counter()
     package_counts: Counter[str] = Counter()
     files: dict[str, int] = {}
@@ -214,13 +171,8 @@ def improvements(measurement: Measurement, baseline: Baseline) -> dict[str, tupl
 
 
 def seed(measurement: Measurement, baseline: Baseline) -> Baseline:
-    """Build the baseline that `--update` would write from a measurement.
-
-    Per-file grandfathering is preserved only where it is still needed: a file
-    that dropped to or below the global ceiling loses its exception, so the
-    allowance cannot outlive the debt it was granted for.
-
-    """
+    """Build the baseline that `--update` would write from a measurement."""
+    # Recompute exceptions so a file loses grandfathering as soon as it reaches the ceiling.
     exceptions = {path: n for path, n in measurement.files.items() if n > baseline.per_file_ceiling}
     return Baseline(
         codes=dict(sorted(measurement.codes.items())),
@@ -231,12 +183,7 @@ def seed(measurement: Measurement, baseline: Baseline) -> Baseline:
 
 
 def load_baseline(path: Path) -> Baseline:
-    """Read a baseline JSON file, ignoring entries of the wrong shape.
-
-    A hand-edited baseline degrades to "not baselined" (ceiling 0) for the
-    malformed entry rather than crashing the gate or silently passing.
-
-    """
+    """Read a baseline JSON file, ignoring entries of the wrong shape."""
     raw: object = json.loads(  # pyright: ignore[reportAny] — json.loads is an untyped stdlib boundary; every read below narrows
         path.read_text(encoding="utf-8")
     )
@@ -281,12 +228,7 @@ def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
 
 
 def discover_packages(root: Path, excluded_dir_names: frozenset[str] = DEFAULT_EXCLUDED_DIR_NAMES) -> list[str]:
-    """List the top-level directories under `root` that contain Python files.
-
-    Used when neither `--package` nor a baseline names the packages, so the
-    first run needs no configuration.
-
-    """
+    """List the top-level directories under `root` that contain Python files."""
     return sorted(
         name
         for child in root.iterdir()
@@ -326,12 +268,7 @@ def _read(path: Path) -> str:
 
 
 def _count_line(line: str, counts: Counter[str]) -> None:
-    """Add one line's suppressions to `counts`.
-
-    The two file-level forms return early: a `# ruff: noqa: X` header is not
-    also an inline `noqa`, and double-counting it would make the two key
-    prefixes overlap.
-    """
+    """Add one line's suppressions to `counts`."""
     file_noqa = _FILE_NOQA_RE.match(line)
     if file_noqa:
         listed = file_noqa.group(1)

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/src/sarj_python_lint/rule_base.py

@@ -20,13 +20,7 @@ REPO_BLOB: Final = "https://github.com/sarj-ai/standards/blob/main"
 TESTS_DIR: Final = "packages/python/tests/rules"
 
 
-# Suppression syntax. Two forms supported:
-#   # sarj-noqa: SARJ001 — reason
-#   # sarj-noqa: SARJ001, SARJ002 — reason
-# We deliberately do NOT reuse ruff's own suppression comment because ruff
-# aggressively cleans unrecognized codes (RUF100/RUF102) even with `external`
-# set, which silently breaks suppressions across runs. A distinct prefix
-# (sarj-noqa) shares no syntax with ruff, so the two never collide.
+# Keep SARJ suppressions separate because Ruff removes unknown `noqa` codes.
 _SARJ_NOQA_RE = re.compile(
     r"#\s*sarj-noqa(?::\s*([A-Za-z0-9_, ]+))?",
     re.IGNORECASE,
@@ -34,11 +28,7 @@ _SARJ_NOQA_RE = re.compile(
 
 
 def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
-    """Report whether the diagnostic's line carries a `# sarj-noqa[: CODE]` comment.
-
-    `line` is 1-based to match Diagnostic.line.
-
-    """
+    """Report whether the diagnostic's line carries a `# sarj-noqa[: CODE]` comment."""
     if line < 1 or line > len(source_lines):
         return False
     text = source_lines[line - 1]
@@ -47,7 +37,7 @@ def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
         return False
     codes_str = m.group(1)
     if not codes_str:
-        # Bare `# sarj-noqa` suppresses every SARJ code on the line
+        # A bare sarj-noqa intentionally suppresses every SARJ code on its line.
         return True
     codes = {val.upper() for c in codes_str.split(",") if (val := c.strip())}
     return code.upper() in codes
@@ -78,14 +68,7 @@ class Diagnostic:
 
 
 class Rule(ABC):
-    """Base class for a single lint rule.
-
-    Subclasses set `id` (kebab-case) and `code` (e.g. SARJ001) as class
-    attributes and implement `check(path, source) -> list[Diagnostic]`.
-
-    A rule documents itself with a concise summary and a derived link to its
-    executable examples. The metadata tests require that paired test module.
-    """
+    """Base class for a single lint rule."""
 
     id: str
     code: str
@@ -93,7 +76,7 @@ class Rule(ABC):
 
     @abstractmethod
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        """Inspect the given source. Return zero or more diagnostics."""
+        """Inspect the given source."""
         raise NotImplementedError
 
     @classmethod

{sarj_python_lint-0.43.0 → sarj_python_lint-0.43.2}/src/sarj_python_lint/rules/_ast_index.py

@@ -1,45 +1,6 @@
-"""One tree traversal per file, shared by every rule that needs node lookups.
-
-Profiling the whole registry over a 1,920-line module showed `ast.walk` and its
-helpers (`iter_child_nodes` / `iter_fields`) accounting for ~60% of all rule
-time. The cause is structural rather than any one rule's fault: the dominant
-shape of a rule is
-
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Something):
-            ...
-
-so a file with N nodes and R rules asking that question pays R full traversals,
-each one re-deriving the same partition of the tree by node type.
-
-`nodes()` derives that partition **once per file** and answers every subsequent
-type query from it. The index is memoized in a single slot keyed on tree
-identity, mirroring `parse_or_none`: the CLI iterates files on the outer loop
-and rules on the inner one, so one slot is all that is ever live. The slot holds
-a strong reference to the tree, so a recycled `id()` can never alias a stale
-index.
-
-Two invariants make the substitution finding-preserving, not merely faster:
-
-* **Order.** The index is built by breadth-first traversal, the same order
-  `ast.walk` yields, and every query preserves it. `nodes(tree, T)` is therefore
-  elementwise equal to `[n for n in ast.walk(tree) if isinstance(n, T)]`, so a
-  rule that takes the *first* match, or reports in discovery order, is
-  unaffected.
-* **Subclasses.** Queries match by `isinstance`, not by exact type: the buckets
-  are keyed on exact class, and a query resolves to the set of present classes
-  that are subclasses of the requested types. Asking for `ast.stmt` still
-  returns every statement.
-
-`walk()` is the same breadth-first order for the cases the index cannot serve —
-traversing a *subtree* rather than the module, where containment is not
-something a whole-module partition can answer.
-
-No rule may mutate the tree. That was already required — every rule shares one
-memoized parse, and `duplicate_test_body` deep-copies before normalizing — and
-the index inherits the requirement, since it holds references into the tree it
-was built from.
-"""
+"""One tree traversal per file, shared by every rule that needs node lookups."""
+
+# Breadth-first order and isinstance semantics intentionally match ast.walk because rules rely on first-match order.
 
 from __future__ import annotations
 
@@ -55,13 +16,7 @@ _AST = ast.AST
 
 
 def children(node: ast.AST) -> list[ast.AST]:
-    """`node`'s direct children, in the same order as `ast.iter_child_nodes`.
-
-    A list rather than a generator: every caller either iterates it once or
-    extends a stack with it, and the hand-rolled walkers in this package call
-    this once per node, where the generator's setup cost dominates the work.
-
-    """
+    """`node`'s direct children, in the same order as `ast.iter_child_nodes`."""
     out: list[ast.AST] = []
     for name in node._fields:
         value: object = getattr(node, name, None)
@@ -73,12 +28,7 @@ def children(node: ast.AST) -> list[ast.AST]:
 
 
 def walk(node: ast.AST) -> Iterator[ast.AST]:
-    """Yield `node` and every descendant, breadth-first.
-
-    Identical in order to `ast.walk`, but reads each node's fields directly
-    instead of routing every node through two intermediate generators.
-
-    """
+    """Yield `node` and every descendant, breadth-first."""
     queue: list[ast.AST] = [node]
     i = 0
     while i < len(queue):
@@ -144,22 +94,13 @@ class _NodeIndex:
 
 
 _last_index: tuple[ast.AST, _NodeIndex] | None = None
+# The strong tree reference prevents a recycled object id from ever reusing a stale index.
 
 
 def nodes[NodeT: ast.AST](tree: ast.AST, *types: type[NodeT]) -> list[NodeT]:
-    """Every node of `tree` matching `types`, in `ast.walk` order.
-
-    A drop-in, memoized replacement for the ubiquitous
-    `[n for n in ast.walk(tree) if isinstance(n, types)]`. Pass the *module*
-    tree: the index is per-file, so calling this with a subtree builds a fresh
-    index and evicts the module's. Use `walk` for subtrees.
-
-    """
+    """Index a whole-file tree; use `walk` for subtrees and never mutate indexed nodes."""
     global _last_index  # ruff: ignore[global-statement] — single-slot memo, mirroring `parse_or_none`
     if _last_index is None or _last_index[0] is not tree:
         _last_index = (tree, _NodeIndex(tree))
     # The `isinstance` pass is what narrows `list[ast.AST]` to `list[NodeT]`
-    # honestly, rather than asserting it with a `cast` the house style bans. It
-    # runs over the matches only — never the tree — and every element passes by
-    # construction, so it costs one type check per node actually returned.
     return [node for node in _last_index[1].query(types) if isinstance(node, types)]