sarj-python-lint 0.16.0__tar.gz → 0.18.0__tar.gz

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.16.0
+Version: 0.18.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

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/pyproject.toml

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

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/__main__.py

@@ -105,6 +105,34 @@ def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
     return counts
 
 
+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.
+
+    Returns:
+        The baseline counts, with any entry of the wrong shape dropped.
+
+    """
+    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]]) -> list[Diagnostic]:
     """Suppress up to the baselined count per (path, code); excess diags survive.
 
@@ -167,7 +195,7 @@ def main(argv: list[str] | None = None) -> int:
         )
         return 0
     if args.baseline is not None:
-        diags = _apply_baseline(diags, json.loads(args.baseline.read_text()))
+        diags = _apply_baseline(diags, _read_baseline(args.baseline))
     for d in diags:
         sys.stdout.write(d.format() + "\n")
     return 1 if diags else 0

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/_secret_names.py

@@ -139,7 +139,8 @@ def identifier_tokens(identifier: str) -> list[str]:
         if not segment:
             continue
         tokens.append(segment.lower())
-        tokens.extend(part.lower() for part in _CAMEL_RE.findall(segment))
+        camel_parts: list[str] = _CAMEL_RE.findall(segment)
+        tokens.extend(part.lower() for part in camel_parts)
     return tokens
 
 
@@ -159,7 +160,7 @@ def leading_word(identifier: str) -> str | None:
     for segment in _SEGMENT_RE.split(identifier):
         if not segment:
             continue
-        parts = _CAMEL_RE.findall(segment)
+        parts: list[str] = _CAMEL_RE.findall(segment)
         return parts[0].lower() if parts else segment.lower()
     return None
 

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/rules/_paths.py

@@ -23,7 +23,12 @@ if TYPE_CHECKING:
 
 _TEST_DIR_NAMES = frozenset({"tests", "test"})
 
-_GENERATED_RE = re.compile(r"auto-?generated|generated by|do not edit", re.IGNORECASE)
+# `auto-?generated` misses "automatically generated", which is the phrase
+# @generated tooling, protoc and OpenAPI generators emit most often.
+_GENERATED_RE = re.compile(
+    r"auto(?:-|matically )?generated|generated by|do not edit|@generated",
+    re.IGNORECASE,
+)
 
 _GENERATED_HEADER_LINES = 5
 

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/rules/_sql.py

@@ -13,6 +13,8 @@ from __future__ import annotations
 import ast
 from typing import TYPE_CHECKING
 
+from sarj_python_lint.rules._paths import is_test_path
+
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -27,10 +29,29 @@ def is_store_module(path: Path) -> bool:
     SQL generator) legitimately writes `SELECT *`, bare `INSERT`, and `COUNT()`,
     so those files are out of scope.
 
+    TEST FILES ARE NEVER STORE MODULES. `test_<x>_store.py` ends with `_store.py`,
+    so the naming test alone swept the *tests for* the store layer into the rules
+    written for the store layer itself. Every store-semantics premise fails there:
+    a test asserts over a handful of per-test fixture rows (so a `COUNT(*)` is not
+    a hot-path aggregation competing with OLTP traffic), and a fixture seeds a row
+    exactly once (so a bare `INSERT` needs no `ON CONFLICT` — idempotency is what
+    the per-test database reset provides). Raw SQL in tests already has its own
+    rule, SARJ036 no-raw-sql-in-tests, which judges it on test-appropriate terms.
+
+    Evidence, bulbul PR #4111 (all suppressed at PR head, none a defect):
+      - SARJ020 `python/bulbul/tests/store/test_batch_call_store.py:2092`, `:2538`
+        ("test assertion count over per-test fixture rows"),
+        `python/bulbul/tests/store/test_global_prompt_store.py:67`
+        ("test asserts exactly one row exists after the upsert").
+      - SARJ018 `python/bulbul/tests/store/test_sip_connection_store.py:37`
+        (`_insert_test_provider` seeding one `phone_provider` row per test).
+
     Returns:
         True when `path` belongs to the store layer.
 
     """
+    if is_test_path(path):
+        return False
     return path.name.endswith("_store.py") or "stores" in path.parts
 
 

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/rules/fixture_returns_bare_tuple.py

@@ -34,7 +34,15 @@ Deliberately NOT flagged:
   mistaken for the smell,
 * a single-element tuple — nothing to mis-order,
 * a starred tuple (`return *pair, extra`) — the arity is not statically known,
-* a tuple returned from a nested helper or closure inside the fixture.
+* a tuple returned from a nested helper or closure inside the fixture,
+* **a fixture annotated `-> tuple[A, B, ...]` whose element types are all
+  syntactically distinct.** The rule's whole argument is that a reorder fails
+  silently — and with distinct static types it does not: swapping the elements
+  is a type error the checker reports at the call site, which is the same
+  protection a `NamedTuple` would buy. Found in bulbul PR #4111 on
+  `python/bulbul/bulbul/tests/fixtures/stores.py:421`, which returns
+  `-> tuple[PsqlOrganizationStore, PsqlUserStore]`. A repeated type
+  (`tuple[str, str]`) still fires: there the reorder really is silent.
 """
 
 from __future__ import annotations
@@ -103,10 +111,39 @@ def _bare_tuple_results(tree: ast.Module) -> list[tuple[ast.expr, int]]:
     for node in ast.walk(tree):
         if not isinstance(node, _FUNC_NODES) or not _is_fixture(node):
             continue
+        if _returns_distinctly_typed_tuple(node):
+            continue
         hits.extend(_tuple_results_of(node))
     return hits
 
 
+def _returns_distinctly_typed_tuple(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """Report whether the fixture is annotated as a tuple of all-distinct types.
+
+    A reorder of `tuple[Store, User]` is a type error the checker catches; a
+    reorder of `tuple[str, str]` is silent. Only the latter is what this rule
+    exists to prevent, so the former is exempt.
+
+    Returns:
+        True when the return annotation is a `tuple[...]` whose element types
+        are pairwise distinct.
+
+    """
+    returns = node.returns
+    if not isinstance(returns, ast.Subscript):
+        return False
+    base = returns.value
+    base_name = base.attr if isinstance(base, ast.Attribute) else base.id if isinstance(base, ast.Name) else None
+    if base_name not in {"tuple", "Tuple"}:
+        return False
+    elts = returns.slice.elts if isinstance(returns.slice, ast.Tuple) else [returns.slice]
+    # `tuple[str, ...]` is a homogeneous sequence, not a record — not our shape.
+    if any(isinstance(e, ast.Constant) and e.value is Ellipsis for e in elts):
+        return False
+    rendered = [ast.dump(e) for e in elts]
+    return len(rendered) >= _MIN_FIELDS and len(set(rendered)) == len(rendered)
+
+
 def _is_fixture(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     return any(_names_fixture(dec) for dec in node.decorator_list)
 

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -34,6 +34,12 @@ References:
 - https://docs.python.org/3/library/stdtypes.html#str.join
 - https://wiki.python.org/moin/PythonSpeed/PerformanceTips
 
+* **generated files** (`_paths.is_generated_source`). Their layout is the
+  generator's, and re-running the generator discards any edit, so a finding
+  there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
+  files git-tracked across bulbul and noura-be — Speakeasy's
+  `python/sdk/src/sarj_platform_sdk/` accounts for all of them.
+
 """
 
 from __future__ import annotations
@@ -42,6 +48,7 @@ import ast
 from typing import TYPE_CHECKING, TypeGuard, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
@@ -58,6 +65,8 @@ class InefficientStringConcatInLoop(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/rules/kwarg_heavy_construction_in_test.py

@@ -31,17 +31,34 @@ a one-line import of a `build_sarj_beneficiary` helper that already exists in
 
 Deliberately NOT flagged:
 
+* **a callee constructed only once in the whole file.** The message promises
+  "every other test repeats the same boilerplate" — so the rule now checks that
+  premise instead of asserting it. A single construction of a domain model with
+  many required fields has no duplication to extract, and telling the author to
+  build a factory for one call site trades real ceremony for nothing. Found in
+  bulbul PR #4111: removing one `# pyright: ignore` forced
+  `python/bulbul/tests/observability/test_analytics_events.py:227` to build a
+  real `Batch(...)` with 12 required fields — the only `Batch(` in the file —
+  and the rule blocked CI over it. Two or more constructions of the same callee
+  still fire: that is the shape a builder actually fixes.
 * calls inside a fixture, a `_make_*` helper, or any non-test function — that is
   the factory, and it is allowed to be verbose exactly once,
 * positional arguments — a call with many positionals is a different smell, and
   ruff's own rules already discourage it,
 * `dict(...)` and literal dict displays — those are data, not a domain object,
-  and naming their keys is the point rather than the problem.
+  and naming their keys is the point rather than the problem,
+* `<mapping>.update(...)` — the same data case one call further on. The keywords
+  are mapping entries being spread, not constructor fields, so there is no
+  object for a builder to build. A 2,657-file third-party sweep produced 14
+  findings and the widest of them (29 keywords) was rich's
+  `table.box.__dict__.update(top_left="a", top="b", ...)`, which relabels box
+  characters wholesale.
 """
 
 from __future__ import annotations
 
 import ast
+from collections import Counter
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
@@ -54,9 +71,16 @@ if TYPE_CHECKING:
 
 _MAX_KEYWORDS = 8
 
+# A builder only pays for itself once the same callee is built more than once.
+_MIN_CONSTRUCTIONS = 2
+
 # `dict(a=1, b=2, ...)` is a mapping literal, not a domain object.
 _DATA_CALLABLES = frozenset({"dict"})
 
+# `<mapping>.update(a=1, b=2, ...)` spreads mapping entries — data again, and no
+# object a builder could construct.
+_DATA_METHODS = frozenset({"update"})
+
 
 class KwargHeavyConstructionInTest(Rule):
     """A >8-keyword construction directly in a test body wants a builder."""
@@ -93,7 +117,7 @@ class KwargHeavyConstructionInTest(Rule):
                     "defaults and override only what this test is about."
                 ),
             )
-            for node, count in visitor.hits
+            for node, count in visitor.repeated_hits(tree)
         ]
         diags.sort(key=lambda d: (d.line, d.col))
         return diags
@@ -135,10 +159,45 @@ class _KwargHeavyVisitor(ast.NodeVisitor):
                 self.hits.append((node, len(named)))
         self.generic_visit(node)
 
+    def repeated_hits(self, tree: ast.Module) -> list[tuple[ast.Call, int]]:
+        """Keep only hits whose callee is constructed more than once in the file.
+
+        Returns:
+            The wide constructions that actually have duplication to extract.
+
+        """
+        counts = Counter(
+            name for n in ast.walk(tree) if isinstance(n, ast.Call) and (name := _callee_name(n.func)) is not None
+        )
+        return [
+            (node, count)
+            for node, count in self.hits
+            # A callee with no stable name (a subscript, a call result) cannot be
+            # counted, so it can never clear the repetition bar.
+            if (name := _callee_name(node.func)) is not None and counts[name] >= _MIN_CONSTRUCTIONS
+        ]
+
     def _in_test_function(self) -> bool:
         nearest = self._func_names[-1] if self._func_names else None
         return nearest is not None and nearest.startswith("test_")
 
 
 def _is_data_callable(func: ast.expr) -> bool:
-    return isinstance(func, ast.Name) and func.id in _DATA_CALLABLES
+    if isinstance(func, ast.Name):
+        return func.id in _DATA_CALLABLES
+    return isinstance(func, ast.Attribute) and func.attr in _DATA_METHODS
+
+
+def _callee_name(func: ast.expr) -> str | None:
+    """Render the callee as a comparable name, so repeats can be counted.
+
+    Returns:
+        The bare or dotted-final name, or None when the callee is an expression
+        with no stable name (a subscript, a call result).
+
+    """
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None

{sarj_python_lint-0.16.0 → sarj_python_lint-0.18.0}/src/sarj_python_lint/rules/kwonly_same_type_params.py

@@ -34,6 +34,12 @@ Never flags — these signatures cannot or should not change:
   `@<name>.get/post/put/patch/delete/head/options/websocket(...)` (`router`,
   `app`, `api`, ...): FastAPI binds handler parameters by NAME (path/query
   keys), so the positional shape is never called swap-prone by a human,
+* CLI command handlers — `@click.*` / `@typer.*`, or `@<name>.command(...)` /
+  `@<name>.group(...)`: click and typer bind handler parameters by NAME from
+  the declared options/arguments and the human call site is a shell command
+  line, not a Python call (3 corpus hits: `httpx/_main.py:452`,
+  `black/src/blackd/__init__.py:96`,
+  `black/scripts/diff_shades_gha_helper.py:167`),
 * test files (`_paths.is_test_path`) — test fakes and helpers mirror the
   signatures of the code under test and cannot unilaterally change them,
 * generated files (`_paths.is_generated_source`) — the signature mirrors
@@ -49,6 +55,31 @@ Never flags — these signatures cannot or should not change:
   (`value_1: float, value_2: float`) — the numbering declares the function
   symmetric, so argument order genuinely does not matter (found via
   pydantic's `almost_equal_floats`),
+* methods that provably override a base-class method — the body calls
+  `super().<same name>(...)`. An override cannot narrow the inherited calling
+  convention without breaking every caller that holds the base type
+  (`httpx/_models.py:1257`, `_CookieCompatRequest.add_unredirected_header`),
+* methods implementing a duck-typed stdlib protocol (`seek`, `read`, `write`,
+  `add_unredirected_header`, `recv`, `setsockopt`, ...). The stdlib itself is
+  the caller and calls them POSITIONALLY — `io` calls `f.seek(0, 2)`,
+  `http.cookiejar` calls `req.add_unredirected_header("Cookie", v)` — so
+  inserting `*` is not a style change, it is a `TypeError` at runtime (5
+  corpus hits: `requests/cookies.py:89` and `:95`, `httpx/_models.py:1257`,
+  `anyio/streams/file.py:97`, `rich/progress.py:270`),
+* parameters named `__x` (leading double underscore, no trailing) — PEP 484
+  spells positional-only parameters that way, so they cannot be made
+  keyword-only at all (`rich/_null_file.py:24`, `NullFile.seek`),
+* same-typed groups drawn entirely from a conventional ordered vocabulary —
+  `x`/`y`/`z`, `width`/`height`, `red`/`green`/`blue`, `start`/`stop`/`step`,
+  `row`/`column`, `top`/`right`/`bottom`/`left`, `year`/`month`/`day`,
+  `hour`/`minute`/`second`. Position IS the notation for these: nobody reads
+  `Control.move(2, 5)` as ambiguous, and `move(*, x=2, y=5)` is worse (11
+  corpus hits, e.g. `rich/control.py:79`, `rich/segment.py:462`,
+  `rich/color.py:409` `from_rgb`, `anyio/itertools.py:271` `count`),
+  The vocabularies are closed sets of domain notation, NOT a general
+  short-name escape: single-letter placeholders stay flagged
+  (`def _newer(a: str, b: str)`, `blib2to3/pgen2/driver.py:287`), because
+  there the call site genuinely cannot tell the two apart.
 * parameters that are already keyword-only (behind `*`) or positional-only
   (before `/`, a deliberate positional API). Note this is per-parameter, not
   per-signature: `def f(a: str, b: str, *, c: int)` is still flagged, because
@@ -84,6 +115,57 @@ _EXEMPT_DECORATORS = frozenset({"override", "overload", "abstractmethod"})
 
 _HTTP_ROUTE_METHODS = frozenset({"get", "post", "put", "patch", "delete", "head", "options", "websocket"})
 
+#: Decorator receivers whose attribute access marks a CLI command handler.
+_CLI_DECORATOR_MODULES = frozenset({"click", "typer"})
+
+#: `@<name>.command(...)` / `@<name>.group(...)` — click groups and typer apps.
+_CLI_DECORATOR_ATTRS = frozenset({"command", "group"})
+
+#: Methods that implement a duck-typed stdlib protocol. The stdlib is the
+#: caller and calls them positionally, so `*` here is a runtime TypeError.
+_DUCK_PROTOCOL_METHODS = frozenset(
+    {
+        "read",
+        "read1",
+        "readinto",
+        "readinto1",
+        "readline",
+        "readlines",
+        "seek",
+        "truncate",
+        "write",
+        "writelines",
+        "connect",
+        "connect_ex",
+        "getsockopt",
+        "setsockopt",
+        "recv",
+        "recv_into",
+        "recvfrom",
+        "recvfrom_into",
+        "send",
+        "sendall",
+        "sendto",
+        "add_header",
+        "add_unredirected_header",
+        "get_header",
+        "has_header",
+    }
+)
+
+#: Parameter-name vocabularies whose ORDER is the notation. A same-typed group
+#: drawn entirely from one of these reads unambiguously positionally.
+_CONVENTIONAL_ORDER_GROUPS = (
+    frozenset({"x", "y", "z"}),
+    frozenset({"width", "height", "depth"}),
+    frozenset({"red", "green", "blue", "alpha"}),
+    frozenset({"row", "column"}),
+    frozenset({"top", "right", "bottom", "left"}),
+    frozenset({"year", "month", "day"}),
+    frozenset({"hour", "minute", "second", "microsecond"}),
+    frozenset({"start", "stop", "step"}),
+)
+
 _EXEMPT_NAME_PREFIXES = ("visit_", "test_")
 
 
@@ -106,6 +188,7 @@ class KwonlySameTypeParams(Rule):
             return []
         value_referenced = _value_referenced_names(tree)
         overload_names = _overload_stub_names(tree)
+        method_ids = _method_node_ids(tree)
         diags: list[Diagnostic] = []
         for node in ast.walk(tree):
             if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
@@ -117,6 +200,10 @@ class KwonlySameTypeParams(Rule):
             offending = _swap_prone_annotation(node.args)
             if offending is None:
                 continue
+            # Checked last: `_calls_super_same_name` walks the body, so it runs
+            # only for the few signatures that would otherwise be reported.
+            if id(node) in method_ids and (node.name in _DUCK_PROTOCOL_METHODS or _calls_super_same_name(node)):
+                continue
             diags.append(
                 Diagnostic(
                     path=path,
@@ -144,10 +231,72 @@ def _is_exempt(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
         (isinstance(dec, ast.Name) and dec.id in _EXEMPT_DECORATORS)
         or (isinstance(dec, ast.Attribute) and dec.attr in _EXEMPT_DECORATORS)
         or _is_route_decorator(dec)
+        or _is_cli_command_decorator(dec)
         for dec in node.decorator_list
     )
 
 
+def _is_cli_command_decorator(dec: ast.expr) -> bool:
+    """Report whether `dec` registers the function as a click/typer CLI handler.
+
+    Matches `@click.*` / `@typer.*` (any attribute: `command`, `option`,
+    `argument`, ...) and `@<name>.command(...)` / `@<name>.group(...)` for a
+    click group or typer app. Both frameworks bind handler parameters by NAME
+    from the declared options, and the human-facing call site is a shell
+    command line — the positional shape is never typed by a caller.
+
+    Returns:
+        True when the decorator is a CLI command registration.
+
+    """
+    target = dec.func if isinstance(dec, ast.Call) else dec
+    match target:
+        case ast.Attribute(value=ast.Name(id=receiver)) if receiver in _CLI_DECORATOR_MODULES:
+            return True
+        case ast.Attribute(value=ast.Name(), attr=attr) if attr in _CLI_DECORATOR_ATTRS:
+            return True
+        case _:
+            return False
+
+
+def _method_node_ids(tree: ast.AST) -> frozenset[int]:
+    """Identify the defs that are methods — direct children of a class body.
+
+    Returns:
+        The set of `id(FunctionDef)` for every method in the module.
+
+    """
+    return frozenset(
+        id(child)
+        for node in ast.walk(tree)
+        if isinstance(node, ast.ClassDef)
+        for child in node.body
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef))
+    )
+
+
+def _calls_super_same_name(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """Report whether the body calls `super().<this method's name>(...)`.
+
+    That call is proof the method overrides an inherited one: its calling
+    convention belongs to the base class, and narrowing it to keyword-only
+    breaks every caller holding the base type.
+
+    Returns:
+        True when the method provably overrides a base-class method.
+
+    """
+    return any(
+        isinstance(call.func, ast.Attribute)
+        and call.func.attr == node.name
+        and isinstance(inner := call.func.value, ast.Call)
+        and isinstance(inner.func, ast.Name)
+        and inner.func.id == "super"
+        for call in ast.walk(node)
+        if isinstance(call, ast.Call)
+    )
+
+
 def _is_route_decorator(dec: ast.expr) -> bool:
     """Report whether `dec` is an HTTP-route decorator like `@router.get(...)`.
 
@@ -178,8 +327,12 @@ def _swap_prone_annotation(args: ast.arguments) -> str | None:
     marker therefore exempts exactly the parameters it protects — never the
     same-type pair sitting in front of it.
 
+    A parameter named `__x` is positional-only by the PEP 484 spelling and so
+    cannot be made keyword-only at all; it never groups.
+
     A group whose parameter names differ only by a numeric suffix
-    (`value_1`/`value_2`) is a declared-symmetric signature and never groups.
+    (`value_1`/`value_2`) or are drawn entirely from a conventional ordered
+    vocabulary (`x`/`y`, `width`/`height`) is not swap-prone and never groups.
 
     Returns:
         The offending primitive name, or None when the signature is fine.
@@ -190,14 +343,43 @@ def _swap_prone_annotation(args: ast.arguments) -> str | None:
         params = params[1:]
     groups: dict[str, list[str]] = {}
     for p in params:
+        if _is_dunder_prefixed(p.arg):
+            continue
         if isinstance(ann := p.annotation, ast.Name) and ann.id in _PRIMITIVES:
             groups.setdefault(ann.id, []).append(p.arg)
     for name, arg_names in sorted(groups.items(), key=lambda kv: -len(kv[1])):
-        if len(arg_names) >= _MIN_SAME_TYPE and not _is_symmetric_numbering(arg_names):
+        if len(arg_names) >= _MIN_SAME_TYPE and not (
+            _is_symmetric_numbering(arg_names) or _is_conventional_order(arg_names)
+        ):
             return name
     return None
 
 
+def _is_dunder_prefixed(arg: str) -> bool:
+    """Report whether `arg` uses the PEP 484 positional-only naming convention.
+
+    Returns:
+        True for a `__name` parameter (leading dunder, no trailing dunder).
+
+    """
+    return arg.startswith("__") and not arg.endswith("__")
+
+
+def _is_conventional_order(arg_names: list[str]) -> bool:
+    """Report whether every name comes from one conventional ordered vocabulary.
+
+    `x`/`y`, `width`/`height`, `red`/`green`/`blue`, `start`/`stop`/`step`:
+    position IS the notation, so the call site is not ambiguous and inserting
+    `*` makes it noisier, not safer.
+
+    Returns:
+        True when the whole group sits inside one ordered vocabulary.
+
+    """
+    names = set(arg_names)
+    return any(names <= vocabulary for vocabulary in _CONVENTIONAL_ORDER_GROUPS)
+
+
 _NUMERIC_SUFFIX_RE = re.compile(r"_?\d+$")