PmCheck: Big refactor using guard tree variants more closely following source syntax (#18565)

Previously, we desugared and coverage checked plain guard trees as
described in Lower Your Guards. That caused (in !3849) quite a bit of
pain when we need to partially recover tree structure of the input
syntax to return covered sets for long-distance information, for
example.

In this refactor, I introduced a guard tree variant for each relevant
source syntax component of a pattern-match (mainly match groups, match,
GRHS, empty case, pattern binding). I made sure to share as much
coverage checking code as possible, so that the syntax-specific checking
functions are just wrappers around the more substantial checking
functions for the LYG primitives (`checkSequence`, `checkGrds`).

The refactoring payed off in clearer code and elimination of all panics
related to assumed guard tree structure and thus fixes #18565.

I also took the liberty to rename and re-arrange the order of functions
and comments in the module, deleted some dead and irrelevant Notes,
wrote some new ones and gave an overview module haddock.

5 files changed, 16 insertions, 4 deletions

diff --git a/testsuite/tests/deSugar/should_compile/ds020.stderr b/testsuite/tests/deSugar/should_compile/ds020.stderr
index e046f327f9..201e819637 100644
--- a/testsuite/tests/deSugar/should_compile/ds020.stderr
+++ b/testsuite/tests/deSugar/should_compile/ds020.stderr
@@ -18,3 +18,11 @@ ds020.hs:20:1: warning: [-Woverlapping-patterns (in -Wdefault)]
 ds020.hs:23:1: warning: [-Woverlapping-patterns (in -Wdefault)]
     Pattern match is redundant
     In an equation for ‘f’: f x@(~[]) = ...
+
+ds020.hs:32:1: warning: [-Woverlapping-patterns (in -Wdefault)]
+    Pattern match is redundant
+    In a pattern binding: (x1 : xs1 : ys1) = ...
+
+ds020.hs:33:1: warning: [-Woverlapping-patterns (in -Wdefault)]
+    Pattern match is redundant
+    In a pattern binding: (~x : ~xs : ~ys) = ...
diff --git a/testsuite/tests/module/all.T b/testsuite/tests/module/all.T
index 2a26edb6e1..7ca6d5d443 100644
--- a/testsuite/tests/module/all.T
+++ b/testsuite/tests/module/all.T
@@ -83,7 +83,7 @@ test('mod61', normal, compile_fail, [''])
 test('mod62', normal, compile_fail, [''])
 test('mod63', normal, compile_fail, [''])
 test('mod64', normal, compile, [''])
-test('mod65', normal, compile, [''])
+test('mod65', normal, compile, ['-Wno-overlapping-patterns'])
 test('mod66', normal, compile_fail, [''])
 test('mod67', normal, compile_fail, [''])
 test('mod68', normal, compile_fail, [''])
diff --git a/testsuite/tests/pmcheck/should_compile/T18572.hs b/testsuite/tests/pmcheck/should_compile/T18572.hs
index 9a37de4813..9a0dd07201 100644
--- a/testsuite/tests/pmcheck/should_compile/T18572.hs
+++ b/testsuite/tests/pmcheck/should_compile/T18572.hs
@@ -3,10 +3,10 @@
 
 module T18572 where
 
-True = True
+True = True -- no warning
 
 data SBool (b :: Bool) where
   STrue :: SBool True
   SFalse :: SBool False
 
-STrue = SFalse
+STrue = SFalse -- "redundant", not "inaccessible"
diff --git a/testsuite/tests/rename/should_compile/T7085.stderr b/testsuite/tests/rename/should_compile/T7085.stderr
index eb54e062eb..6b60f62f48 100644
--- a/testsuite/tests/rename/should_compile/T7085.stderr
+++ b/testsuite/tests/rename/should_compile/T7085.stderr
@@ -1,3 +1,7 @@
 
 T7085.hs:8:6: warning: [-Wunused-pattern-binds (in -Wextra, -Wunused-binds)]
     This pattern-binding binds no variables: Nothing = Just n
+
+T7085.hs:8:6: warning: [-Woverlapping-patterns (in -Wdefault)]
+    Pattern match is redundant
+    In a pattern binding: Nothing = ...
diff --git a/testsuite/tests/unboxedsums/all.T b/testsuite/tests/unboxedsums/all.T
index b400735464..764a850aec 100644
--- a/testsuite/tests/unboxedsums/all.T
+++ b/testsuite/tests/unboxedsums/all.T
@@ -30,5 +30,5 @@ test('T12711', only_ways(['ghci']), ghci_script, ['T12711.script'])
 #       extra_files([ "unboxedsums" + str(i) + ".hs" for i in range(1, 12) ])],
 #      makefile_test, [])
 
-test('UbxSumLevPoly', normal, compile, [''])
+test('UbxSumLevPoly', normal, compile, ['-Wno-overlapping-patterns'])
 test('T14051', normal, multi_compile, ['T14051.hs', [('T14051a.hs', '')], '-O2 -v0'])