Improve kind generalisation, error messages

This patch does two things:

* It refactors GHC.Tc.Errors a bit.  In debugging Quick Look I was
  forced to look in detail at error messages, and ended up doing a bit
  of refactoring, esp in mkTyVarEqErr'.  It's still quite a mess, but
  a bit better, I think.

* It makes a significant improvement to the kind checking of type and
  class declarations. Specifically, we now ensure that if kind
  checking fails with an unsolved constraint, all the skolems are in
  scope.  That wasn't the case before, which led to some obscure error
  messages; and occasional failures with "no skolem info" (eg #16245).

Both of these, and the main Quick Look patch itself, affect a /lot/ of
error messages, as you can see from the number of files changed.  I've
checked them all; I think they are as good or better than before.

Smaller things

* I documented the various instances of VarBndr better.
  See Note [The VarBndr tyep and its uses] in GHC.Types.Var

* Renamed GHC.Tc.Solver.simpl_top to simplifyTopWanteds

* A bit of refactoring in bindExplicitTKTele, to avoid the
  footwork with Either.  Simpler now.

* Move promoteTyVar from GHC.Tc.Solver to GHC.Tc.Utils.TcMType

Fixes #16245 (comment 211369), memorialised as
  typecheck/polykinds/T16245a
Also fixes the three bugs in #18640

3 files changed, 13 insertions, 16 deletions

diff --git a/testsuite/tests/patsyn/should_fail/T15685.stderr b/testsuite/tests/patsyn/should_fail/T15685.stderr
index 37627b852b..e081453659 100644
--- a/testsuite/tests/patsyn/should_fail/T15685.stderr
+++ b/testsuite/tests/patsyn/should_fail/T15685.stderr
@@ -1,19 +1,13 @@
 
 T15685.hs:13:24: error:
-    • Couldn't match kind ‘a1’ with ‘[k0]’
-      When matching types
-        f :: a1 -> *
-        NP a0 :: [k0] -> *
-      Expected: f a2
-        Actual: NP a0 b0
-        ‘a1’ is untouchable
-          inside the constraints: as ~ (a2 : as1)
-          bound by a pattern with constructor:
-                     Here :: forall {a1} (f :: a1 -> *) (a2 :: a1) (as :: [a1]).
-                             f a2 -> NS f (a2 : as),
-                   in a pattern synonym declaration
-          at T15685.hs:13:19-26
-      ‘a1’ is a rigid type variable bound by
+    • Could not deduce: a ~ [k0]
+      from the context: as ~ (a1 : as1)
+        bound by a pattern with constructor:
+                   Here :: forall {a1} (f :: a1 -> *) (a2 :: a1) (as :: [a1]).
+                           f a2 -> NS f (a2 : as),
+                 in a pattern synonym declaration
+        at T15685.hs:13:19-26
+      ‘a’ is a rigid type variable bound by
         the inferred type of HereNil :: NS f as
         at T15685.hs:13:9-15
       Possible fix: add a type signature for ‘HereNil’
diff --git a/testsuite/tests/patsyn/should_fail/T15694.stderr b/testsuite/tests/patsyn/should_fail/T15694.stderr
index 360fb30ba2..7e1507c332 100644
--- a/testsuite/tests/patsyn/should_fail/T15694.stderr
+++ b/testsuite/tests/patsyn/should_fail/T15694.stderr
@@ -1,4 +1,7 @@
 
 T15694.hs:22:35: error:
-    • Expected kind ‘k1 -> k00’, but ‘f a1’ has kind ‘ks’
+    • Expected kind ‘k1 -> k0’, but ‘f a1’ has kind ‘ks’
+      ‘ks’ is a rigid type variable bound by
+        the data constructor ‘ASSO’
+        at T15694.hs:18:30-31
     • In the first argument of ‘(~~)’, namely ‘f a1 a2’
diff --git a/testsuite/tests/patsyn/should_fail/T15695.stderr b/testsuite/tests/patsyn/should_fail/T15695.stderr
index 2e834c6d08..82398e15a7 100644
--- a/testsuite/tests/patsyn/should_fail/T15695.stderr
+++ b/testsuite/tests/patsyn/should_fail/T15695.stderr
@@ -1,7 +1,7 @@
 
 T15695.hs:39:14: warning: [-Wdeferred-type-errors (in -Wdefault)]
     • Could not deduce: a2 ~ NA 'VO
-      from the context: ((* -> * -> *) ~ (k1 -> k2 -> *), Either ~~ f,
+      from the context: ((* -> * -> *) ~ (k -> k1 -> *), Either ~~ f,
                          ctx ~~ (a2 ':&: (a3 ':&: 'E)), f a2 ~~ f1, f1 a3 ~~ a4)
         bound by a pattern with pattern synonym:
                    ASSO :: forall kind (a :: kind) (b :: Ctx kind).