Add remaining-patterns-unreachable checker.

This will emit an error message when a name capture pattern is used
in a match statement which would make the remaining patterns unreachable.
This code is a SyntaxError at runtime.

Closes #7128

Author: mbyrnepr2

doc/data/messages/u/unreachable-match-patterns/bad.py

@@ -0,0 +1,13 @@
+red = 0
+green = 1
+blue = 2
+
+
+color = blue
+match color:
+    case red:  # [unreachable-match-patterns]
+        print("I see red!")
+    case green:  # [unreachable-match-patterns]
+        print("Grass is green")
+    case blue:
+        print("I'm feeling the blues :(")

doc/data/messages/u/unreachable-match-patterns/good.py

@@ -0,0 +1,15 @@
+from enum import Enum
+class Color(Enum):
+    RED = 0
+    GREEN = 1
+    BLUE = 2
+
+
+color = Color.BLUE
+match color:
+    case Color.RED:
+        print("I see red!")
+    case Color.GREEN:
+        print("Grass is green")
+    case Color.BLUE:
+        print("I'm feeling the blues :(")

doc/data/messages/u/unreachable-match-patterns/related.rst

@@ -0,0 +1 @@
+- `PEP 636 <https://peps.python.org/pep-0636/#matching-against-constants-and-enums/>`_

doc/user_guide/checkers/features.rst

@@ -1343,6 +1343,18 @@ Unnecessary Ellipsis checker Messages
   preceding line or if there is a statement in the same scope.
 
 
+Unreachable Match Patterns checker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Verbatim name of the checker is ``unreachable_match_patterns``.
+
+Unreachable Match Patterns checker Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:unreachable-match-patterns (E5000): *The name capture `case %s` makes the remaining patterns unreachable. Use a dotted name(for example an enum) to fix this*
+  Emitted when a name capture pattern in a match statement is used and there
+  are case statements below it.
+
+
 Unsupported Version checker
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/user_guide/messages/messages_overview.rst

@@ -165,6 +165,7 @@ All messages in the error category:
    error/unexpected-special-method-signature
    error/unhashable-member
    error/unpacking-non-sequence
+   error/unreachable-match-patterns
    error/unrecognized-inline-option
    error/unrecognized-option
    error/unsubscriptable-object

doc/whatsnew/fragments/7128.new_check

@@ -0,0 +1,5 @@
+Add ``unreachable-match-patterns`` checker.
+This will emit an error message when a name capture pattern is used in a match statement which would make the remaining patterns unreachable.
+This code is a SyntaxError at runtime.
+
+Closes #7128

pylint/checkers/match_statements_checker.py

@@ -0,0 +1,59 @@
+# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+# For details: https://github.com/pylint-dev/pylint/blob/main/LICENSE
+# Copyright (c) https://github.com/pylint-dev/pylint/blob/main/CONTRIBUTORS.txt
+
+"""Match statement checker for Python code."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from astroid import nodes
+
+from pylint.checkers import BaseChecker
+from pylint.checkers.utils import only_required_for_messages
+from pylint.interfaces import HIGH
+
+if TYPE_CHECKING:
+    from pylint.lint import PyLinter
+
+
+class MatchStatementChecker(BaseChecker):
+    name = "unreachable_match_patterns"
+    msgs = {
+        "E5000": (
+            "The name capture `case %s` makes the remaining patterns unreachable. "
+            "Use a dotted name(for example an enum) to fix this",
+            "unreachable-match-patterns",
+            "Emitted when a name capture pattern in a match statement is used "
+            "and there are case statements below it.",
+        )
+    }
+
+    def open(self) -> None:
+        py_version = self.linter.config.py_version
+        self._py310_plus = py_version >= (3, 10)
+
+    @only_required_for_messages("unreachable-match-patterns")
+    def visit_match(self, node: nodes.Match) -> None:
+        """Check if a name capture pattern prevents the other cases from being
+        reached
+        """
+        for idx, case in enumerate(node.cases):
+            if (
+                isinstance(case.pattern, nodes.MatchAs)
+                and case.pattern.pattern is None
+                and isinstance(case.pattern.name, nodes.AssignName)
+                and idx < len(node.cases) - 1
+                and self._py310_plus
+            ):
+                self.add_message(
+                    "unreachable-match-patterns",
+                    node=case,
+                    args=case.pattern.name.name,
+                    confidence=HIGH,
+                )
+
+
+def register(linter: PyLinter) -> None:
+    linter.register_checker(MatchStatementChecker(linter))

tests/functional/u/unreachable_match_patterns.py

@@ -0,0 +1,15 @@
+"""Functional tests for the ``unreachable-match-patterns`` check"""
+
+
+a = 'a'
+b = 'b'
+s = 'a'
+
+
+match s:
+    case a:  # [unreachable-match-patterns]
+        pass
+    case b:  # [unreachable-match-patterns]
+        pass
+    case s:
+        pass

tests/functional/u/unreachable_match_patterns.rc

@@ -0,0 +1,2 @@
+[testoptions]
+min_pyver=3.10

tests/functional/u/unreachable_match_patterns.txt

@@ -0,0 +1,2 @@
+unreachable-match-patterns:10:0:None:None::The name capture `case a` makes the remaining patterns unreachable. Use a dotted name(for example an enum) to fix this:HIGH
+unreachable-match-patterns:12:0:None:None::The name capture `case b` makes the remaining patterns unreachable. Use a dotted name(for example an enum) to fix this:HIGH