sarj-python-lint 0.11.0__tar.gz → 0.12.0__tar.gz

{sarj_python_lint-0.11.0 → sarj_python_lint-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.11.0
+Version: 0.12.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.11.0 → sarj_python_lint-0.12.0}/pyproject.toml

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

{sarj_python_lint-0.11.0 → sarj_python_lint-0.12.0}/src/sarj_python_lint/rules/_registry.py

@@ -5,8 +5,6 @@ from typing import TYPE_CHECKING
 from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
     InefficientStringConcatInLoop,
 )
-from sarj_python_lint.rules.json_response_not_parsed import JsonResponseNotParsed
-from sarj_python_lint.rules.len_as_truthiness import LenAsTruthiness
 from sarj_python_lint.rules.no_aggregation_in_store_query import (
     NoAggregationInStoreQuery,
 )
@@ -17,7 +15,6 @@ from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
 from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
 from sarj_python_lint.rules.no_fstring_in_log import NoFstringInLog
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
-from sarj_python_lint.rules.no_manual_log_prefix import NoManualLogPrefix
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
 from sarj_python_lint.rules.no_query_with_many_joins import NoQueryWithManyJoins
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
@@ -64,10 +61,7 @@ REGISTRY: dict[str, type[Rule]] = {
     NoIsinstanceUnionChain.id: NoIsinstanceUnionChain,
     NoOffsetPagination.id: NoOffsetPagination,
     PreferNamedtupleOverTupleReturn.id: PreferNamedtupleOverTupleReturn,
-    LenAsTruthiness.id: LenAsTruthiness,
     NoCorsWildcardWithCredentials.id: NoCorsWildcardWithCredentials,
-    NoManualLogPrefix.id: NoManualLogPrefix,
-    JsonResponseNotParsed.id: JsonResponseNotParsed,
     NoSleepInTestBody.id: NoSleepInTestBody,
     PydanticAtBoundaries.id: PydanticAtBoundaries,
     NoSentinelReturnOnExcept.id: NoSentinelReturnOnExcept,

{sarj_python_lint-0.11.0 → sarj_python_lint-0.12.0}/src/sarj_python_lint/rules/_sql.py

@@ -11,6 +11,23 @@ before any keyword or comment scan.
 from __future__ import annotations
 
 import ast
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def is_store_module(path: Path) -> bool:
+    """True for a store-layer module: basename ends `_store.py`, or the file lives under a `stores/` directory.
+
+    The SQL store-lint rules (SARJ018/020/021) encode store-write semantics —
+    column-naming, ON-CONFLICT upserts, no Postgres-side aggregation — that only
+    apply to the store layer. Non-store SQL (Flask view handlers, a Django ORM
+    SQL generator) legitimately writes `SELECT *`, bare `INSERT`, and `COUNT()`,
+    so those files are out of scope.
+    """
+    return path.name.endswith("_store.py") or "stores" in path.parts
 
 
 def sql_string_value(node: ast.expr) -> str | None:

sarj_python_lint-0.12.0/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -0,0 +1,175 @@
+"""SARJ002: detect O(n²) single-accumulator string growth inside loops.
+
+Growing a string with `s += <str>` or `s = s + <str>` inside a loop is O(n²)
+in CPython because strings are immutable — each step allocates a new string and
+copies the previous one. Append to a list and `"".join(parts)` at the end for
+O(n).
+
+The rule fires only on genuine single-string accumulation. It deliberately does
+NOT treat a `str()/repr()/format()` coercion, a `.join()` / `.format()` /
+`.strftime()` call, or an `os.path.join(...)`-style call as accumulation — those
+are either the prescribed remedy or a bounded per-iteration transform, not the
+O(n²) defect. Per-slot writes (`parts[i] = ...`) and idempotent rebinding
+(`x = f(x)`) are likewise excluded.
+
+References:
+- https://docs.python.org/3/library/stdtypes.html#str.join
+- https://wiki.python.org/moin/PythonSpeed/PerformanceTips
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class InefficientStringConcatInLoop(Rule):
+    """O(n²) string concatenation in a loop."""
+
+    id: str = "inefficient-string-concat-in-loop"
+    code: str = "SARJ002"
+    description: str = "`s += '...'` / `s = s + '...'` in a loop is O(n²); append to a list and join."
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        visitor = _ConcatVisitor()
+        visitor.visit(tree)
+        return [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message="String concat in a loop is O(n²). Append to a list and `''.join(...)`.",
+            )
+            for node in visitor.hits
+        ]
+
+
+class _ConcatVisitor(ast.NodeVisitor):
+    """Single O(n) pass flagging each in-loop string accumulation exactly once."""
+
+    def __init__(self) -> None:
+        self._loop_depth: int = 0
+        self._string_vars: list[frozenset[str]] = [frozenset()]
+        self.hits: list[ast.AugAssign | ast.Assign] = []
+
+    @override
+    def generic_visit(self, node: ast.AST) -> None:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            saved_depth = self._loop_depth
+            self._loop_depth = 0
+            self._string_vars.append(_string_typed_locals(node))
+            super().generic_visit(node)
+            self._string_vars.pop()
+            self._loop_depth = saved_depth
+            return
+        if isinstance(node, (ast.For, ast.AsyncFor, ast.While)):
+            self._loop_depth += 1
+            super().generic_visit(node)
+            self._loop_depth -= 1
+            return
+        if self._loop_depth and self._is_in_loop_concat(node):
+            self.hits.append(node)
+        super().generic_visit(node)
+
+    def _is_in_loop_concat(self, node: ast.AST) -> bool:
+        if isinstance(node, ast.AugAssign):
+            return isinstance(node.op, ast.Add) and self._is_string_growth(node.target, node.value)
+        if isinstance(node, ast.Assign):
+            return any(self._is_self_add_growth(target, node.value) for target in node.targets)
+        return False
+
+    def _is_self_add_growth(self, target: ast.expr, value: ast.expr) -> bool:
+        """`s = s + <str>` — a BinOp(Add) rebinding the target to itself-plus-more."""
+        if not isinstance(value, ast.BinOp) or not isinstance(value.op, ast.Add):
+            return False
+        other = _other_add_operand(target, value)
+        if other is None:
+            return False
+        return self._is_string_growth(target, other)
+
+    def _is_string_growth(self, target: ast.expr, rhs: ast.expr) -> bool:
+        """True when appending `rhs` to `target` is single-string accumulation."""
+        if isinstance(target, ast.Subscript):
+            return False
+        if _looks_like_string(rhs):
+            return True
+        if isinstance(rhs, ast.Name) and isinstance(target, ast.Name):
+            return target.id in self._string_vars[-1]
+        return False
+
+
+def _other_add_operand(target: ast.expr, binop: ast.BinOp) -> ast.expr | None:
+    """The non-target operand of `target + x` / `x + target`, or None if absent."""
+    target_src = ast.unparse(target)
+    if ast.unparse(binop.left) == target_src:
+        return binop.right
+    if ast.unparse(binop.right) == target_src:
+        return binop.left
+    return None
+
+
+def _string_typed_locals(func: ast.AST) -> frozenset[str]:
+    """Names assigned a string-literal-ish value in this function's own body.
+
+    Used as the string-typed signal for bare-`Name` accumulation (`buf += line`):
+    a numeric accumulator (`total = 0`) is absent, so `total += x` stays clean.
+    """
+    body = getattr(func, "body", None)
+    if not isinstance(body, list):
+        return frozenset()
+    names: set[str] = set()
+    for stmt in body:
+        _collect_string_targets(stmt, names)
+    return frozenset(names)
+
+
+def _collect_string_targets(node: ast.AST, names: set[str]) -> None:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)):
+        return
+    if isinstance(node, ast.Assign) and _looks_like_string(node.value):
+        for target in node.targets:
+            if isinstance(target, ast.Name):
+                names.add(target.id)
+    if (
+        isinstance(node, ast.AnnAssign)
+        and node.value is not None
+        and isinstance(node.target, ast.Name)
+        and _looks_like_string(node.value)
+    ):
+        names.add(node.target.id)
+    for child in ast.iter_child_nodes(node):
+        _collect_string_targets(child, names)
+
+
+def _looks_like_string(node: ast.AST) -> bool:
+    """Heuristic for 'this expression is obviously a string at runtime'.
+
+    Deliberately conservative: a bare call (`str(x)`, `",".join(...)`,
+    `os.path.join(...)`) is NOT treated as a string — those shapes also appear in
+    benign one-shot reassignment and are not the accumulation defect.
+    """
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return True
+    if isinstance(node, ast.JoinedStr):  # f-string
+        return True
+    if isinstance(node, ast.NamedExpr):  # walrus `(y := <str>)`
+        return _looks_like_string(node.value)
+    if isinstance(node, ast.IfExp):  # ternary — string only if both branches are
+        return _looks_like_string(node.body) and _looks_like_string(node.orelse)
+    if isinstance(node, ast.BinOp):
+        if isinstance(node.op, ast.Add):
+            return _looks_like_string(node.left) or _looks_like_string(node.right)
+        if isinstance(node.op, ast.Mod):  # `"row %s" % x` — left operand decides
+            return _looks_like_string(node.left)
+    return False

{sarj_python_lint-0.11.0 → sarj_python_lint-0.12.0}/src/sarj_python_lint/rules/no_aggregation_in_store_query.py

@@ -38,7 +38,7 @@ import re
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
-from sarj_python_lint.rules._sql import sql_string_value, strip_sql_noise
+from sarj_python_lint.rules._sql import is_store_module, sql_string_value, strip_sql_noise
 
 
 if TYPE_CHECKING:
@@ -121,6 +121,8 @@ class NoAggregationInStoreQuery(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_store_module(path):
+            return []
         # A diagnostic needs some string literal that carries both a query verb
         # and an aggregation keyword; `source` is a strict superset of every
         # literal, so if either class is absent from the whole file no diagnostic

{sarj_python_lint-0.11.0 → sarj_python_lint-0.12.0}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -20,7 +20,10 @@ readability audit, not this rule):
    block of `#` lines.
 
 Deliberately NOT flagged: trailing/standalone *prose* comments (the legitimate
-"why"), and directive comments — `# type:`, `# noqa`, `# sarj-noqa`,
+"why"); code-shaped *illustrations* — a line that parses as Python but sits
+under a prose lead-in (`# For example:`, a wrapped sentence) or carries
+pseudo-code markers (`%sent%`, `[opt]`, `<FunctionBody>`, `...`); and directive
+comments — `# type:`, `# noqa`, `# sarj-noqa`,
 `# pragma:`, `# pyright:`, `# mypy:`, `# fmt:`, `# isort:`, `# ruff:`,
 `# nosec`, `# TODO`, `# FIXME`, shebangs, and coding declarations.
 
@@ -43,6 +46,7 @@ if TYPE_CHECKING:
 
 
 _LEADING_PREAMBLE_MIN = 4
+_PROSE_MIN_WORDS = 3
 
 _DIRECTIVE_PREFIXES = (
     "type:",
@@ -90,6 +94,11 @@ _CODE_HEADER_RE = re.compile(
 )
 _ASSIGN_OR_CALL_RE = re.compile(r"^[A-Za-z_][\w.\[\]]*\s*(?:=|:=|\+=|-=|\*=|/=)\s*\S|^[A-Za-z_][\w.]*\(")
 
+# Pseudo-code / grammar-example markers (`%sent%`, `[opt]`, `<FunctionBody>`,
+# `...`). Real commented-out code doesn't carry these — they mark an
+# illustration inside a doc comment, not a line that was once executed.
+_PSEUDOCODE_RE = re.compile(r"%[^%\s]+%|\[opt\]|<[^<>]+>|\.\.\.")
+
 
 def _comment_body(raw: str) -> str:
     return raw.lstrip("#").strip()
@@ -125,6 +134,8 @@ def _looks_like_code(body: str) -> bool:
     c = body.strip()
     if not c:
         return False
+    if _PSEUDOCODE_RE.search(c):
+        return False
     if _CODE_STMT_RE.match(c):
         return _compiles(c)
     if _RISKY_STMT_RE.match(c):
@@ -138,6 +149,23 @@ def _looks_like_code(body: str) -> bool:
     return False
 
 
+def _is_prose_line(body: str) -> bool:
+    """Return True if `body` reads as a natural-language sentence, not code.
+
+    Used to spot a doc/prose comment that immediately precedes a code-shaped
+    line: `# For example:` above `# result = {**a, **b}`, or a wrapped sentence
+    whose second line happens to parse as an expression. Such a line is an
+    illustration / prose continuation, not commented-out code.
+    """
+    c = body.strip()
+    if not c or _is_banner(c) or _is_directive(c) or _looks_like_code(c):
+        return False
+    if c.endswith(":"):
+        return True
+    words = [w for w in re.split(r"\s+", c) if any(ch.isalpha() for ch in w)]
+    return len(words) >= _PROSE_MIN_WORDS
+
+
 def _compiles(snippet: str) -> bool:
     try:
         ast.parse(snippet)
@@ -176,20 +204,24 @@ class NoCommentCruft(Rule):
         except tokenize.TokenError, IndentationError, SyntaxError:
             return []
         diags: dict[int, Diagnostic] = {}
+        by_line = {line: body for line, _, body in standalone}
         for line, col, body in standalone:
             if _is_directive(body):
                 continue
-            msg = self._classify(body)
+            prev_body = by_line.get(line - 1)
+            msg = self._classify(body, prev_body)
             if msg is not None:
                 diags[line] = Diagnostic(path=path, line=line, col=col + 1, code=self.code, message=msg)
         self._flag_leading_preamble(standalone, first_code_line, path, diags)
         return [diags[k] for k in sorted(diags)]
 
     @staticmethod
-    def _classify(body: str) -> str | None:
+    def _classify(body: str, prev_body: str | None) -> str | None:
         if _is_banner(body):
             return "Section-banner / region comment — structure code with functions, not ASCII rules."
         if _looks_like_code(body):
+            if prev_body is not None and _is_prose_line(prev_body):
+                return None
             return "Commented-out code — delete it; git history remembers."
         return None
 

{sarj_python_lint-0.11.0 → sarj_python_lint-0.12.0}/src/sarj_python_lint/rules/no_fstring_in_log.py

@@ -18,9 +18,16 @@ To keep false positives near zero we require BOTH a logger-like receiver
 (`logger`/`log`/`logging`/`loguru` and common aliases) AND a logging method
 name — an f-string passed to some unrelated `.info(...)` is not flagged. The
 receiver chain is resolved, so builder/factory forms are still caught:
-`logger.bind(...).info(...)`, `logger.opt(lazy=True).debug(...)`, and
-`logging.getLogger(__name__).warning(...)`. Only the first positional argument
-(the message) is inspected.
+`logger.bind(...).info(...)`, `logger.opt(lazy=True).debug(...)`. Only the first
+positional argument (the message) is inspected.
+
+The structured-keyword advice is loguru-specific: stdlib `logging` treats
+trailing positional args as %-format parameters and reserves `exc_info` /
+`stack_info` / `extra` keywords, so rewriting a stdlib call to
+`logger.info("msg", key=value)` would silently break it. We therefore suppress
+calls that carry a stdlib tell — a `logging.getLogger(...)` factory anywhere in
+the receiver chain, or an `exc_info` / `stack_info` / `extra` keyword — and keep
+firing on the loguru-shaped calls the advice actually applies to.
 
 Suppress an intentional case with `# sarj-noqa: SARJ017 — <reason>`.
 """
@@ -54,6 +61,11 @@ _LOG_METHODS = frozenset(
     }
 )
 
+# Keyword arguments defined by stdlib `logging` (and never structured fields).
+# Their presence marks the call as a stdlib logger, for which the loguru-style
+# structured-keyword rewrite is wrong.
+_STDLIB_ONLY_KWARGS = frozenset({"exc_info", "stack_info", "extra"})
+
 
 class NoFstringInLog(Rule):
     """f-string passed as a logging message — use structured keyword arguments."""
@@ -76,6 +88,8 @@ class NoFstringInLog(Rule):
                 continue
             if not node.args:
                 continue
+            if _is_stdlib_logging_call(node):
+                continue
             offending = _interpolating_fstring(node.args[0])
             if offending is not None:
                 diags.append(
@@ -100,6 +114,36 @@ def _is_logging_call(node: ast.Call) -> bool:
     return is_logger_expr(func.value)
 
 
+def _is_stdlib_logging_call(node: ast.Call) -> bool:
+    """True when the call carries a stdlib-`logging` tell the loguru advice breaks.
+
+    Either a stdlib-reserved keyword (`exc_info`/`stack_info`/`extra`) or a
+    `logging.getLogger(...)` factory anywhere in the receiver chain marks the
+    logger as stdlib, whose message API is %-style positional, not structured
+    keywords — so the rule must stay silent to avoid recommending a broken fix.
+    """
+    if any(kw.arg in _STDLIB_ONLY_KWARGS for kw in node.keywords):
+        return True
+    func = node.func
+    return isinstance(func, ast.Attribute) and _chain_has_getlogger(func.value)
+
+
+def _chain_has_getlogger(expr: ast.expr) -> bool:
+    node = expr
+    while True:
+        if isinstance(node, ast.Call):
+            called = node.func
+            if isinstance(called, ast.Attribute) and called.attr == "getLogger":
+                return True
+            if isinstance(called, ast.Name) and called.id == "getLogger":
+                return True
+            node = called
+        elif isinstance(node, ast.Attribute):
+            node = node.value
+        else:
+            return False
+
+
 def _interpolating_fstring(node: ast.expr) -> ast.JoinedStr | None:
     """Find an interpolating f-string in `node`, descending `+`-concat operands.
 

sarj_python_lint-0.12.0/src/sarj_python_lint/rules/no_isinstance_union_chain.py

@@ -0,0 +1,249 @@
+"""SARJ003: flag `if/elif isinstance(...)` chains that dispatch over a *local* closed union.
+
+A chain of `if isinstance(x, A): ... elif isinstance(x, B): ... else: raise` where every
+`A`, `B`, ... is a class **defined in this same module** and the chain terminates
+exhaustively is dispatch over a locally-owned discriminated union. `match`/`case` with
+`assert_never` in the fallthrough is strictly better: pyright reports an error the moment a
+new variant is added and a branch is missed — a plain `isinstance` chain silently falls
+through.
+
+    # flagged
+    class ApiKeySubject: ...
+    class JwtSubject: ...
+
+    if isinstance(subject, ApiKeySubject):
+        ...
+    elif isinstance(subject, JwtSubject):
+        ...
+    else:
+        assert_never(subject)
+
+    # preferred
+    match subject:
+        case ApiKeySubject():
+            ...
+        case JwtSubject():
+            ...
+        case _:
+            assert_never(subject)
+
+The rule fires ONLY when both gates hold, because only then is a mechanical rewrite to an
+exhaustive `match` both correct and beneficial:
+
+1. **Local-union gate.** Every `isinstance` arm tests a bare `ast.Name` that resolves to an
+   `ast.ClassDef` in this module — not an imported name, not a dotted `pkg.Cls`, not a
+   builtin/stdlib type. Probing open-set types the module does not own
+   (`property`, `cached_property`, `Path`, `Decimal`, `dataclasses.Field`, ...) is a
+   legitimate runtime check, not closed-union dispatch, and is never flagged.
+2. **Exhaustiveness gate.** The chain ends in a terminal `else`/final branch that raises,
+   returns, asserts, or calls an `assert_never`-style helper. An *open* chain — no `else`,
+   or a permissive `else` that silently falls through — is not equivalent to an exhaustive
+   `match` and must not be flagged, since converting it would change behavior.
+
+This is still a heuristic (a locally-defined class could be re-exported, an imported class
+could be the real union member). Suppress a deliberate boundary chain with
+`# sarj-noqa: SARJ003 — <reason>`.
+
+References:
+- https://docs.python.org/3/library/typing.html#typing.assert_never
+- https://typing.python.org/en/latest/spec/narrowing.html#assert-never-and-exhaustiveness-checking
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# A dispatch chain needs at least this many `isinstance` arms to be flagged.
+_MIN_CHAIN_LENGTH = 2
+
+# `isinstance(x, T)` takes exactly two positional arguments.
+_ISINSTANCE_ARG_COUNT = 2
+
+# Belt-and-suspenders: names that must never count as a local union member even if a
+# same-named class happens to be defined in the module (a domain class named `Sequence`
+# shadowing the ABC, a local `class Exception`, etc.). The primary gate is still
+# "resolves to a local ClassDef"; this denylist only ever *removes* names from that set.
+_EXCLUDED_TYPE_NAMES = frozenset(
+    {
+        "dict",
+        "str",
+        "list",
+        "tuple",
+        "set",
+        "frozenset",
+        "int",
+        "float",
+        "bool",
+        "complex",
+        "bytes",
+        "bytearray",
+        "type",
+        "object",
+        "Exception",
+        "BaseException",
+        "NoneType",
+        "Unset",
+        "datetime",
+        "date",
+        "time",
+        "timedelta",
+        "Mapping",
+        "MutableMapping",
+        "Sequence",
+        "MutableSequence",
+        "Iterable",
+        "Iterator",
+        "Collection",
+        "Container",
+        "Set",
+        "Hashable",
+        "Callable",
+    }
+)
+
+
+class NoIsinstanceUnionChain(Rule):
+    """`if/elif isinstance` chains over local classes — prefer match/case + assert_never."""
+
+    id: str = "no-isinstance-union-chain"
+    code: str = "SARJ003"
+    description: str = (
+        "if/elif isinstance chain over locally-defined classes with an exhaustive "
+        "terminal — prefer match/case with assert_never for compile-time exhaustiveness."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        local_classes = frozenset(
+            node.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef)
+        )
+        elif_nodes: set[int] = set()
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.If):
+                continue
+            if len(node.orelse) == 1 and isinstance(node.orelse[0], ast.If):
+                elif_nodes.add(id(node.orelse[0]))
+            if id(node) in elif_nodes:
+                continue
+            count = _qualifying_chain_length(node, local_classes)
+            if count >= _MIN_CHAIN_LENGTH:
+                diags.append(
+                    Diagnostic(
+                        path=path,
+                        line=node.lineno,
+                        col=node.col_offset + 1,
+                        code=self.code,
+                        message=(
+                            f"if/elif isinstance chain over {count} local classes — prefer "
+                            "match/case with assert_never for exhaustiveness."
+                        ),
+                    )
+                )
+        return diags
+
+
+def _qualifying_chain_length(head: ast.If, local_classes: frozenset[str]) -> int:
+    """Number of arms if `head` is a local-closed-union dispatch chain, else 0.
+
+    Requires every arm to be `isinstance(<same target>, <local ClassDef name>)` and the
+    chain to end in an exhaustive terminal `else` (raise / return / assert / assert_never).
+    """
+    first_target: ast.expr | None = None
+    count = 0
+    current: ast.If | None = head
+    while current is not None:
+        parsed = _isinstance_single_type(current.test)
+        if parsed is None:
+            return 0
+        target, type_node = parsed
+        if not isinstance(type_node, ast.Name):
+            return 0
+        type_name = type_node.id
+        if type_name in _EXCLUDED_TYPE_NAMES or type_name not in local_classes:
+            return 0
+        if first_target is None:
+            first_target = target
+        elif not _ast_equal(target, first_target):
+            return 0
+        count += 1
+        orelse = current.orelse
+        if len(orelse) == 1 and isinstance(orelse[0], ast.If):
+            current = orelse[0]
+        else:
+            if not _is_exhaustive_terminal(orelse):
+                return 0
+            current = None
+    return count
+
+
+def _is_exhaustive_terminal(orelse: list[ast.stmt]) -> bool:
+    """True if the trailing `else` block terminates instead of silently falling through.
+
+    An open chain (no `else`) or a permissive `else` that just does work and continues is
+    NOT equivalent to an exhaustive `match`, so it does not qualify.
+    """
+    if not orelse:
+        return False
+    return any(_stmt_terminates(stmt) for stmt in orelse)
+
+
+def _stmt_terminates(stmt: ast.stmt) -> bool:
+    match stmt:
+        case ast.Raise() | ast.Return() | ast.Assert():
+            return True
+        case ast.Expr(value=ast.Call(func=func)):
+            return _is_assert_never(func)
+        case _:
+            return False
+
+
+def _is_assert_never(func: ast.expr) -> bool:
+    match func:
+        case ast.Name(id="assert_never"):
+            return True
+        case ast.Attribute(attr="assert_never"):
+            return True
+        case _:
+            return False
+
+
+def _ast_equal(a: object, b: object) -> bool:
+    """Structural equality equivalent to `ast.dump(a) == ast.dump(b)`, without building
+    the dump strings. Recursively compares node types and their `_fields`; leaves compare
+    by type + repr to mirror ast.dump's value rendering (e.g. `1` vs `1.0`, `True` vs `1`)
+    exactly while avoiding the per-subtree string allocation ast.dump pays."""
+    if isinstance(a, ast.AST):
+        if type(a) is not type(b):
+            return False
+        return all(_ast_equal(getattr(a, field, None), getattr(b, field, None)) for field in a._fields)
+    if isinstance(a, list):
+        if not isinstance(b, list) or len(a) != len(b):
+            return False
+        return all(map(_ast_equal, a, b, strict=True))
+    return type(a) is type(b) and repr(a) == repr(b)
+
+
+def _isinstance_single_type(test: ast.expr) -> tuple[ast.expr, ast.expr] | None:
+    """If `test` is `isinstance(x, T)` with a single (non-tuple) type argument, return
+    (target, type_node); else None. Tuple-form `isinstance(x, (A, B))` returns a Tuple
+    type_node, which the caller rejects (not an `ast.Name`)."""
+    if not isinstance(test, ast.Call):
+        return None
+    if not (isinstance(test.func, ast.Name) and test.func.id == "isinstance"):
+        return None
+    if len(test.args) != _ISINSTANCE_ARG_COUNT or test.keywords:
+        return None
+    target, type_node = test.args
+    return target, type_node